From 39a6261dd5ffcdc76386077b0ae72974086c88d0 Mon Sep 17 00:00:00 2001 From: Christian Caspers Date: Tue, 3 Dec 2024 18:03:44 +0100 Subject: [PATCH] docs(@nestjs/swagger): document description support in @ApiSchema --- content/openapi/types-and-parameters.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/content/openapi/types-and-parameters.md b/content/openapi/types-and-parameters.md index 05b53a873e..15c7c3fdfc 100644 --- a/content/openapi/types-and-parameters.md +++ b/content/openapi/types-and-parameters.md @@ -345,7 +345,7 @@ pets: Pet[]; Both `Cat` and `Dog` must be defined as extra models using the `@ApiExtraModels()` decorator (at the class-level). -#### Schema name +#### Schema name and description As you may have noticed, the name of the generated schema is based on the name of the original model class (for example, the `CreateCatDto` model generates a `CreateCatDto` schema). If you'd like to change the schema name, you can use the `@ApiSchema()` decorator. @@ -357,3 +357,19 @@ class CreateCatDto {} ``` The model above will be translated into the `CreateCatRequest` schema. + +By default, no description is added to the generated schema. You can add one like this + +```typescript +@ApiSchema({ description: 'Description of the CreateCatDto schema' }) +class CreateCatDto {} +``` + +That way, the description will be rendered like this + +```yaml +schemas: + CreateCatDto: + type: object + description: Description of the CreateCatDto schema +```