[discussion]: add decorator for setting the description for a schema

[gerriet]

Is there an existing issue that is already proposing this?

• [X] I have searched the existing issues

Is your feature request related to a problem? Please describe it

OpenAPI allows a description not only for single properties but also for a complete schema. This can be optionally validated via no_schema_description in OpenAPI validator. Currently I see no way to set this description via a decorator.

Describe the solution you'd like

In correspondence with (PR 983)[https://github.com/nestjs/swagger/pull/983], where ApiSchema would be used with property name, this could work with a decorator named ApiSchema and a property named description, e.g.

@ApiSchema({ description: "Describing my schema" })
class MyDto {}

Teachability, documentation, adoption, migration strategy

No response

What is the motivation / use case for changing the behavior?

Richer OpenAPI documentation with descriptions for schemata

[kamilmysliwiec]

Would you like to create a PR to #983 with this feature?

[gerriet]

Yes, I would. How should I go about it? Wait for #983 to be merged? Copy the current PR changes into a new PR that covers both name and description?

[kamilmysliwiec]

Use #983 as a base branch and create a PR to that branch

[raplemie]

Could the "title" be included as well ?

[corentinguilloux]

The related PR has actually been locked for one year, anything new about it ?

[gwesterman]

Any news? Using this library I cannot get the API to pass the internal linting requirements of my client.

[SBD580]

As a workaround you can do this:

class Example {
}

export { Example as ExampleDto }

This will leave your code the same but will cause the schemas to be with a different name

[mothershipper]

Just want to chime in here -- I cherry-picked the original author's commits into a new PR (#2427), happy to take ownership of any requested changes to the OG PR, I could really use this feature 😅

[kamilmysliwiec]

Let's track this here https://github.com/nestjs/swagger/pull/2427