From 7ad1deb83d0fb1f858525054ca8aa8990ba78f60 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vin=C3=ADcius=20Louren=C3=A7o?= Date: Mon, 17 Apr 2023 13:38:33 -0300 Subject: [PATCH 1/3] docs(openapi): prefer lazy over eager creation of the document --- content/openapi/introduction.md | 8 ++++---- content/openapi/other-features.md | 8 ++++---- content/openapi/types-and-parameters.md | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/content/openapi/introduction.md b/content/openapi/introduction.md index d9a95c0d5b..8090ff986d 100644 --- a/content/openapi/introduction.md +++ b/content/openapi/introduction.md @@ -29,15 +29,15 @@ async function bootstrap() { .setVersion('1.0') .addTag('cats') .build(); - const document = SwaggerModule.createDocument(app, config); - SwaggerModule.setup('api', app, document); + const documentFactory = () => SwaggerModule.createDocument(app, config); + SwaggerModule.setup('api', app, documentFactory); await app.listen(3000); } bootstrap(); ``` -> info **Hint** `document` (returned by the `SwaggerModule#createDocument()` method) is a serializable object conforming to [OpenAPI Document](https://swagger.io/specification/#openapi-document). Instead of hosting it via HTTP, you could also save it as a JSON/YAML file, and consume it in different ways. +> info **Hint** The return of `SwaggerModule#createDocument()` is a serializable object conforming to [OpenAPI Document](https://swagger.io/specification/#openapi-document). Instead of hosting it via HTTP, you could also save it as a JSON/YAML file, and consume it in different ways. The `DocumentBuilder` helps to structure a base document that conforms to the OpenAPI Specification. It provides several methods that allow setting such properties as title, description, version, etc. In order to create a full document (with all HTTP routes defined) we use the `createDocument()` method of the `SwaggerModule` class. This method takes two arguments, an application instance and a Swagger options object. Alternatively, we can provide a third argument, which should be of type `SwaggerDocumentOptions`. More on this in the [Document options section](/openapi/introduction#document-options). @@ -126,7 +126,7 @@ const options: SwaggerDocumentOptions = { methodKey: string ) => methodKey }; -const document = SwaggerModule.createDocument(app, config, options); +const documentFactory = () => SwaggerModule.createDocument(app, config, options); ``` #### Setup options diff --git a/content/openapi/other-features.md b/content/openapi/other-features.md index 33a63ceea7..b572f52f15 100644 --- a/content/openapi/other-features.md +++ b/content/openapi/other-features.md @@ -47,10 +47,10 @@ async function bootstrap() { .addTag('cats') .build(); - const catDocument = SwaggerModule.createDocument(app, options, { + const catDocumentFactory = () => SwaggerModule.createDocument(app, options, { include: [CatsModule], }); - SwaggerModule.setup('api/cats', app, catDocument); + SwaggerModule.setup('api/cats', app, catDocumentFactory); const secondOptions = new DocumentBuilder() .setTitle('Dogs example') @@ -59,10 +59,10 @@ async function bootstrap() { .addTag('dogs') .build(); - const dogDocument = SwaggerModule.createDocument(app, secondOptions, { + const dogDocumentFactory = () => SwaggerModule.createDocument(app, secondOptions, { include: [DogsModule], }); - SwaggerModule.setup('api/dogs', app, dogDocument); + SwaggerModule.setup('api/dogs', app, dogDocumentFactory); await app.listen(3000); } diff --git a/content/openapi/types-and-parameters.md b/content/openapi/types-and-parameters.md index 2bf60bd6c3..eca31b6df9 100644 --- a/content/openapi/types-and-parameters.md +++ b/content/openapi/types-and-parameters.md @@ -251,7 +251,7 @@ export class CreateCatDto {} Alternatively, you can pass an options object with the `extraModels` property specified to the `SwaggerModule#createDocument()` method, as follows: ```typescript -const document = SwaggerModule.createDocument(app, options, { +const documentFactory = () => SwaggerModule.createDocument(app, options, { extraModels: [ExtraModel], }); ``` From 941126bef1f9ba071844defc244aa25f9c901b85 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vin=C3=ADcius=20Louren=C3=A7o?= Date: Sun, 9 Jul 2023 11:11:57 -0300 Subject: [PATCH 2/3] fixup! docs(openapi): prefer lazy over eager creation of the document --- content/openapi/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/openapi/introduction.md b/content/openapi/introduction.md index 8090ff986d..565237976f 100644 --- a/content/openapi/introduction.md +++ b/content/openapi/introduction.md @@ -37,7 +37,7 @@ async function bootstrap() { bootstrap(); ``` -> info **Hint** The return of `SwaggerModule#createDocument()` is a serializable object conforming to [OpenAPI Document](https://swagger.io/specification/#openapi-document). Instead of hosting it via HTTP, you could also save it as a JSON/YAML file, and consume it in different ways. +> info **Hint** The factory around `SwaggerModule#createDocument()` is only used to create the document when you actually request Swagger, saving some initialization time and is a serializable object conforming to [OpenAPI Document](https://swagger.io/specification/#openapi-document). Instead of hosting it via HTTP, you could also save it as a JSON/YAML file, and consume it in different ways. The `DocumentBuilder` helps to structure a base document that conforms to the OpenAPI Specification. It provides several methods that allow setting such properties as title, description, version, etc. In order to create a full document (with all HTTP routes defined) we use the `createDocument()` method of the `SwaggerModule` class. This method takes two arguments, an application instance and a Swagger options object. Alternatively, we can provide a third argument, which should be of type `SwaggerDocumentOptions`. More on this in the [Document options section](/openapi/introduction#document-options). From 13da8e003ddb2d81a704f087a1446172f336eaa8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kamil=20My=C5=9Bliwiec?= Date: Thu, 17 Oct 2024 12:51:01 +0200 Subject: [PATCH 3/3] chore: improve wording --- content/openapi/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/openapi/introduction.md b/content/openapi/introduction.md index 024550e0f1..dce1500241 100644 --- a/content/openapi/introduction.md +++ b/content/openapi/introduction.md @@ -37,7 +37,7 @@ async function bootstrap() { bootstrap(); ``` -> info **Hint** The factory around `SwaggerModule#createDocument()` is only used to create the document when you actually request Swagger, saving some initialization time and is a serializable object conforming to [OpenAPI Document](https://swagger.io/specification/#openapi-document). Instead of hosting it via HTTP, you could also save it as a JSON/YAML file, and consume it in different ways. +> info **Hint** The factory method `SwaggerModule#createDocument()` is used specifically to generate the Swagger document when you request it. This approach helps save some initialization time, and the resulting document is a serializable object that conforms to the [OpenAPI Document](https://swagger.io/specification/#openapi-document) specification. Instead of serving the document over HTTP, you can also save it as a JSON or YAML file and use it in various ways. The `DocumentBuilder` helps to structure a base document that conforms to the OpenAPI Specification. It provides several methods that allow setting such properties as title, description, version, etc. In order to create a full document (with all HTTP routes defined) we use the `createDocument()` method of the `SwaggerModule` class. This method takes two arguments, an application instance and a Swagger options object. Alternatively, we can provide a third argument, which should be of type `SwaggerDocumentOptions`. More on this in the [Document options section](/openapi/introduction#document-options).