Integrate Swagger Documentation in Nest.js application

Integrate Swagger Documentation in Nest.js application

To implement Swagger documentation in a Nest.js application and document your APIs, you can use the @nestjs/swagger package, which provides decorators for defining Swagger metadata. Follow these steps to set up Swagger documentation:

Install the necessary packages:

                        npm install --save @nestjs/swagger swagger-ui-express
                       

Create a swagger.ts

Configure Swagger in your Nest.js application. Create a `swagger.ts` file (or any other name you prefer) in your project's root directory:

                        // swagger.ts
                        import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
                        import { INestApplication } from '@nestjs/common';
                        
                        export function setupSwagger(app: INestApplication) {
                          const options = new DocumentBuilder()
                            .setTitle('Your API Title')
                            .setDescription('Your API Description')
                            .setVersion('1.0')
                            .addTag('user')
                            .build();
                        
                          const document = SwaggerModule.createDocument(app, options);
                          SwaggerModule.setup('api', app, document);
                        }
                        
                       

Import and call setupSwagger in your main.ts

Import and call setupSwagger in your main.ts file (or the entry file for your Nest.js application):

                        // main.ts
                       import { NestFactory } from '@nestjs/core';
                       import { AppModule } from './app.module';
                       import { setupSwagger } from './swagger';
                    
                       async function bootstrap() {
                         const app = await NestFactory.create(AppModule);
                         setupSwagger(app);
                         await app.listen(3000);
                       }
                       bootstrap();
                    
                       

Decorate your Controller

Decorate your StudentController and its endpoints with Swagger decorators. Here's how to do it:

                        import { Controller, Post, Body, Res } from '@nestjs/common';
                        import { ApiTags, ApiResponse, ApiBadRequestResponse } from '@nestjs/swagger';
                        import { AuthGuard } from 'your-auth-guard-module-path'; // Import your AuthGuard
                    
                        @Controller('v1/user')
                        @ApiTags('user') // Add a tag for the controller
                        @UseGuards(AuthGuard) // Apply your AuthGuard
                        export class StudentController {
                          constructor(private readonly studentService: StudentService) {}
                    
                          @Post('/register')
                          @ApiResponse({ status: 201, description: 'User has been created successfully' })
                          @ApiBadRequestResponse({ description: 'Bad Request' })
                          async createStudent(@Res() response, @Body() createStudentDto: CreateStudentDto): Promise<any> {
                            const newStudent = await this.studentService.createStudent(createStudentDto);
                            return response.json({
                              message: 'User has been created successfully',
                              newStudent,
                            });
                          }
                        }
                    
                       

We use @ApiTags('user') to specify a tag for the controller.
@ApiResponse is used to document the successful response.
@ApiBadRequestResponse is used to document the response when a bad request occurs.

Run you app and Access API Docs

Start your Nest.js application (npm run start) and access Swagger UI by visiting http://localhost:3000/api (assuming your app is running on port 3000). You will see the Swagger documentation for your API, including the StudentController and its endpoints.

Make sure to customize the Swagger options and response descriptions according to your API's needs.

---

Conclusion:

In conclusion, implementing Swagger documentation in a Nest.js application is a straightforward process that enhances the overall developer experience and helps in maintaining well-documented APIs. By following the steps outlined in this guide, you can easily generate API documentation for your controllers and endpoints:

Related Keywords:

Integrate Swagger Documentation in Nest.js application

Integrating Swagger with NestJS: A Step-by-Step Guide

OpenAPI (Swagger) with NestJS - A progressive Node.js

Documenting NestJS APIs With Swagger

A Guide to NestJS Swagger Configuration

Integrating Swagger/OpenAPI with NestJS