NESTJS API DOCUMENTATION WITH SWAGGER

Introduction

Swagger is a popular open-source framework for generating interactive API documentation. It allows you to document your APIs in a comprehensive and user-friendly way, making it easy for developers to use and understand.

NestJS is a progressive Node.js framework that provides a dedicated module for using Swagger. This module makes it easy to generate API documentation for your NestJS APIs.

Benefits of using swagger

There are many benefits to using Swagger to document your APIs, including:

• Improved developer experience:  Swagger documentation is easy to read and understand, making it easier for developers to learn how to use your APIs.
• Reduced development time: Swagger can help to reduce development time by automating the process of generating API documentation.
• Improved API quality: Swagger documentation can help to improve the quality of your APIs by identifying potential errors and inconsistencies.
• Increased API adoption: Swagger documentation can help to increase adoption of your APIs by making it easier for developers to learn how to use them.

How to use swagger with NestJS

To use Swagger with NestJS, you first need to install the @nestjs/swagger package:

npm install --save @nestjs/swagger

Once the package is installed, you can import the SwaggerModule and DocumentBuilder classes into your NestJS application:

import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

Next, you need to create a new instance of the DocumentBuilder class. This class allows you to configure the basic properties of your Swagger documentation, such as the title, description, and version.

const config = new DocumentBuilder()
  .setTitle('My NestJS API')
  .setDescription('The API description')
  .setVersion('1.0')
  .addTag('my-api')
  .build();

Once you have created a new instance of the DocumentBuilder class, you can use it to generate a Swagger document for your NestJS application:

const document = SwaggerModule.createDocument(app, config);

Finally, you need to mount the Swagger UI to your NestJS application:

SwaggerModule.setup('api', app, document);

Once you have completed these steps, you can view your Swagger documentation at http://localhost:<PORT>/api.

Swagger Decorators

NestJS provides a number of decorators that you can use to document your NestJS APIs. These decorators allow you to specify the following information for each endpoint:

• Path: The HTTP path of the endpoint.
• Method: The HTTP method of the endpoint (GET, POST, PUT, DELETE).
• Summary: A short summary of the endpoint.
• Description: A detailed description of the endpoint.
• Request body: The schema of the request body.
• Response body: The schema of the response body.

To use a Swagger decorator, simply add it to the controller method that corresponds to the endpoint that you want to document. For example, the following code shows how to document a GET endpoint that returns a list of users:

@Get('/users')
async getUsers() {
  // ...
}

The @Get() decorator specifies that this is a GET endpoint and the /users path. The @ApiOperation() decorator specifies the summary and description of the endpoint.

You can also use Swagger decorators to document the request and response bodies of your endpoints. For example, the following code shows how to document a POST endpoint that creates a new user:

@Post('/users')
async createUser(@RequestBody() user: UserDto) {
  // ...
}

The @RequestBody() decorator specifies that the request body should be of the UserDto type.

Conclusion

Swagger is a powerful tool for generating API documentation. NestJS provides a dedicated module for using Swagger, making it easy to generate documentation for your NestJS APIs. By using Swagger to document your APIs, you can improve the developer experience, reduce development time, improve API quality, and increase API adoption.

For more such posts, please follow our LinkedIn page- FrontEnd Competency.