From 39a6261dd5ffcdc76386077b0ae72974086c88d0 Mon Sep 17 00:00:00 2001 From: Christian Caspers Date: Tue, 3 Dec 2024 18:03:44 +0100 Subject: [PATCH 1/3] 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 +``` From f2f566f44024a300541db5435198928446bacc5c Mon Sep 17 00:00:00 2001 From: Kamil Mysliwiec Date: Wed, 4 Dec 2024 10:32:08 +0100 Subject: [PATCH 2/3] Update content/openapi/types-and-parameters.md --- content/openapi/types-and-parameters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/openapi/types-and-parameters.md b/content/openapi/types-and-parameters.md index 15c7c3fdfc..95bb5449b4 100644 --- a/content/openapi/types-and-parameters.md +++ b/content/openapi/types-and-parameters.md @@ -358,7 +358,7 @@ 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 +By default, no description is added to the generated schema. You can add one using the `description` attribute: ```typescript @ApiSchema({ description: 'Description of the CreateCatDto schema' }) From 151fdd697d83d7937be0c068360f8cce486f1c26 Mon Sep 17 00:00:00 2001 From: Kamil Mysliwiec Date: Wed, 4 Dec 2024 10:32:16 +0100 Subject: [PATCH 3/3] Update content/openapi/types-and-parameters.md --- content/openapi/types-and-parameters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/openapi/types-and-parameters.md b/content/openapi/types-and-parameters.md index 95bb5449b4..fdb7e1a70d 100644 --- a/content/openapi/types-and-parameters.md +++ b/content/openapi/types-and-parameters.md @@ -365,7 +365,7 @@ By default, no description is added to the generated schema. You can add one usi class CreateCatDto {} ``` -That way, the description will be rendered like this +That way, the description will be included in the schema, as follows: ```yaml schemas: