The title property MUST NOT be used because it hides the actual data type name in visualization tools like Swagger UI.
However, title property is useful in two cases:
for inline schemas, to override the generated class name (e.g. openapi-generator). Currently, inline schemas are often moved to top-level schemas under components bc of this, even though they're not really reusable.
redocly viewer sometimes messes up, showing the name of a parent schema inside 'oneOf'/'anyOf'
So I propose to change this to:
For schemas defined under components, the title property MUST NOT override the name of the schema because it would hide the actual schema name in visualization tools like Swagger UI.
Current rule: https://www.belgif.be/specification/rest/api-guide/#rule-oas-descr
However, title property is useful in two cases:
componentsbc of this, even though they're not really reusable.So I propose to change this to:
For schemas defined under
components, thetitleproperty MUST NOT override the name of the schema because it would hide the actual schema name in visualization tools like Swagger UI.