Swagger supports both JSON and XML payloads. The documentation it generates is suitable for developers and non-developers to use.
You can document your NestJS web APIs via Swagger using simple decorators, without having to leave your IDE.
Step 1: Generating the API
Before starting, you must create a demo API that Swagger will generate its documentation.
You will generate the demo API from scratch using the NestJS CLI.
Firstly, generate a new NestJS project by running:
Then, change the directory to your already created project by running:
Next, you’ll generate a REST API with the CLI by running:
You’ll see a query asking, “What transport layer do you use?” select REST API.
You’ll see another query asking, “Would you like to generate CRUD entry points?” Type Y and hit Enter.
The command above generates a fully functional REST API with CRUD endpoints and without the unit test files. Hence, the –no-spec flag in the command above.
Step 2: Install Swagger
Install Swagger and its Express UI library by running:
Step 3: Configure Swagger
In your main.ts file, import SwaggerModule and DocumentBuilder from @nestjs/swagger.
DocumentBuilder assists in the structuring of a base document. It provides several methods that you can chain together and close with the build method.
These methods enable the configuration of many attributes, such as title, description, and version.
Create a config object variable in your bootstrap function like so:
A new instance of DocumentBuilder creates a base document that matches the OpenAPI Specification. You can then use this instance to set the title, description, and version via their appropriate methods.
Next, you’ll need to create a complete document with all the HTTP routes defined using the base document.
To do this, call the createDocument method on SwaggerModule. createDocument accepts two arguments: an application instance and a Swagger options object. Store the result of this call in a variable for later use:
Next, call the setup method on SwaggerModule. The setup method takes in three arguments:
The Swagger UI path. By convention, you can use “api”. An application instance The full document
Additionally, the setup method takes an optional options object. See NestJS’s documentation on Swagger document options to learn more about it.
Like so:
Start your application and go to http://localhost:
You should see the Swagger UI displayed on the page.
The image above is the default view of the Swagger UI, with all the HTTP routes in your controller defined. You’ll need to customize it to fit your API functionality.
Step 4: Customize API Properties
By default, Swagger prefixes the entire HTTP route section with a heading that reads “default.” You can change this by annotating your controller class with the @ApiTags decorator and passing your preferred tag as an argument.
Like so:
The Schemas section contains the Data-transfer objects in your API. Currently, the UI includes none of their properties.
To declare their properties in the UI, simply add decorators. Annotate each required property with the @ApiProperty decorator. Annotate optional properties with the @ApiPropertyOptional decorator.
For example:
The @ApiProperty and @ApiPropertyOptional decorators each accept an options object. That object describes the property that follows below.
Note that the options object uses JavaScript, not TypeScript. Hence the JavaScript type declarations (i.e. String, not string).
Annotating the Data-transfer object’s properties adds an example of the expected data to the Schemas section. It also updates the associated HTTP route with an example of the expected data.
Step 5: Set API Responses
In your controller class, use the @ApiResponse decorators to document all potential responses for each HTTP route. For each endpoint, the different @ApiResponse decorators describe the type of responses to expect.
We’ve explained common HTTP responses, in case you’re unfamiliar with what they mean.
The @ApiResponse decorators accept an optional object that describes the response.
Common POST Responses
For a POST request, the likely responses include:
ApiCreatedResponse, for successful 201 created responses. ApiUnprocessableEnityResponse, for failed 422 unprocessable entity responses. ApiForbiddenResponse, for 403 forbidden responses.
For example:
Common GET Responses
For GET requests, the likely responses include:
ApiOkResponse, for 200 ok responses. ApiForbiddenResponse, for 403 forbidden responses. ApiNotFoundResponse, for 404 not-found responses.
For example:
Common PATCH and UPDATE Responses
For PATCH and UPDATE requests, the likely responses include:
ApiOkResponse, for 200 ok responses. ApiNotFoundResponse, for 404 not-found responses. ApiUnprocessibleEntityResponse, for failed 422 unprocessable entity responses. ApiForbiddenResponse, for 403 forbidden responses.
For example:
Common DELETE Responses
For DELETE requests, the likely responses include:
ApiOkResponse, for 200 ok responses. ApiForbiddenResponse, for 403 forbidden responses. ApiNotFoundResponse, for 404 not-found responses.
For example:
These decorators populate your documentation with possible responses. You can view them using the drop-down alongside each route.
Viewing Your Documentation
When your setup is complete, you can view your documentation on localhost:
The essentials of Swagger API documentation are the description, response types, and schema definition. These are the basic things needed to create good API documentation.
