OpenAPI 3.0 spec definition creates an invalid spec document

[ksemasinghe]

The open-api spec generation for 3.0 creates an invalid spec for requestBody.content[0].schema

TSOA will define a description entry if the relevant controller's route has a jsdoc definition for @body.

My understanding is that the OpenAPI spec does not list description as an actual valid key if the $ref specifier is used, meaning setting it would be invalid.

This causes an issue as we are using a tool called ingress2gateway to generate a different spec from the OpenAPI definition. That tool appears to be strict in that it detects this description key as an invalid reference.

Is it possible to not set these extra values if we are using a $ref to define the mediaType?

[github-actions]

Hello there ksemasinghe 👋

Thank you for opening your very first issue in this project.

We will try to get back to you as soon as we can.👀

[ksemasinghe]

We've also noticed another instance where this happens.

We had a type define as ResponseType = Omit<OtherType, "key_1">

and typed the route response as Promise<ResponseType>.

The generated api spec also added a description alongside the $ref in this case, causing another breakage

[WoH]

This object cannot be extended with additional properties, and any properties added SHALL be ignored.

That reads like it's not illegal.