Integrating Swagger for API Documentation in NestJS

As the complexity of modern web applications increases, having a comprehensive and accessible API documentation becomes essential. Swagger is a powerful tool for generating API documentation and is widely adopted in the industry. NestJS, a progressive Node.js framework, seamlessly integrates with Swagger, enabling developers to document their APIs with ease.

In this article, we’ll walk through the steps to integrate Swagger for API documentation in a NestJS project. We will cover the initial setup, creating decorators for your endpoints, and generating the Swagger documentation.

Prerequisites

Before we proceed, ensure that you have Node.js installed on your machine. You can download it from the official Node.js website. Additionally, you should have NestJS installed globally. You can do this by running:

npm install -g @nestjs/cli

Step 1: Setting Up a New NestJS Project

To get started, create a new NestJS project:

nest new my-nestjs-project
cd my-nestjs-project

Step 2: Installing Swagger Dependencies

NestJS provides a dedicated package for integrating Swagger. Install the package along with its dependencies:

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

Step 3: Configuring Swagger

Once the dependencies are installed, we need to set up Swagger in the main application file (main.ts). Import the necessary modules and configure Swagger as follows:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('NestJS API')
    .setDescription('The API description')
    .setVersion('1.0')
    .addTag('cats')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();

This configuration sets up a Swagger documentation accessible at /api when the application is running.

Step 4: Adding Swagger Decorators

To document your API endpoints, you need to annotate your code with Swagger decorators. Below is an example of a basic CatsController with Swagger decorators:

import { Controller, Get, Post, Body } from '@nestjs/common';
import { ApiTags, ApiOperation, ApiResponse, ApiBody } from '@nestjs/swagger';

class CreateCatDto {
  name: string;
  age: number;
  breed: string;
}

@Controller('cats')
@ApiTags('cats')
export class CatsController {

  @Get()
  @ApiOperation({ summary: 'Get all cats' })
  @ApiResponse({ status: 200, description: 'Successfully retrieved cats.' })
  @ApiResponse({ status: 403, description: 'Forbidden.' })
  findAll() {
    // Your logic for fetching all cats
    return 'This action returns all cats';
  }

  @Post()
  @ApiOperation({ summary: 'Create a cat' })
  @ApiBody({ type: CreateCatDto })
  @ApiResponse({ status: 201, description: 'Cat successfully created.' })
  @ApiResponse({ status: 403, description: 'Forbidden.' })
  create(@Body() createCatDto: CreateCatDto) {
    // Your logic for creating a new cat
    return 'This action adds a new cat';
  }
}

In the above code:

• @ApiTags groups endpoints under a specific tag.
• @ApiOperation provides a summary of what the endpoint does.
• @ApiResponse specifies the possible responses.
• @ApiBody describes the structure of the request body.

Step 5: Testing Our API Documentation

Run your application using:

npm run start

Open your browser and navigate to http://localhost:3000/api. You should see your Swagger UI with documentation for the endpoints defined in CatsController.

Conclusion

Integrating Swagger with your NestJS application not only improves the usability of your API but also makes it easier for developers to understand and interact with it. With a few simple steps, you can have a robust, auto-generated API documentation right alongside your codebase.

By leveraging decorators and the power of NestJS, you can ensure that your documentation is always up-to-date and reflective of your API’s capabilities.

Happy coding!