How to Use Swagger in NestJS for API Documentation

To use Swagger in NestJS, install @nestjs/swagger and swagger-ui-express, then configure Swagger in your main application file using SwaggerModule. This setup auto-generates interactive API documentation accessible via a URL like /api.

Syntax

Here is the basic syntax to set up Swagger in a NestJS app:

• SwaggerModule.createDocument(app, options): Generates the Swagger document from your app and options.
• SwaggerModule.setup(path, app, document): Serves the Swagger UI at the given path.
• DocumentBuilder: Helps build the Swagger config like title, description, and version.

typescript

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

const config = new DocumentBuilder()
  .setTitle('API Title')
  .setDescription('API description')
  .setVersion('1.0')
  .build();

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

Example

This example shows a minimal NestJS app with Swagger configured to serve docs at /api. It demonstrates how to import modules, create the Swagger config, and start the server.

typescript

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('Cats API')
    .setDescription('The cats API description')
    .setVersion('1.0')
    .build();

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

  await app.listen(3000);
  console.log('Application is running on: http://localhost:3000');
  console.log('Swagger docs available at: http://localhost:3000/api');
}
bootstrap();

Output

Application is running on: http://localhost:3000
Swagger docs available at: http://localhost:3000/api

Common Pitfalls

Common mistakes when using Swagger in NestJS include:

• Not installing @nestjs/swagger and swagger-ui-express packages.
• Forgetting to import SwaggerModule and configure it in the main file.
• Not adding decorators like @ApiTags or @ApiProperty on controllers and DTOs, which limits documentation detail.
• Setting up Swagger after app.listen(), which prevents docs from loading.

Correct setup order and proper decorators ensure full API docs.

typescript

/* Wrong: Swagger setup after app.listen() */
await app.listen(3000);
SwaggerModule.setup('api', app, document); // This won't work properly

/* Right: Swagger setup before app.listen() */
SwaggerModule.setup('api', app, document);
await app.listen(3000);

Quick Reference

Here is a quick cheat-sheet for using Swagger in NestJS:

Step	Description
Install packages	npm install @nestjs/swagger swagger-ui-express
Import SwaggerModule	import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger'
Create config	Use DocumentBuilder to set title, description, version
Generate document	SwaggerModule.createDocument(app, config)
Setup UI	SwaggerModule.setup('api', app, document)
Add decorators	Use @ApiTags, @ApiProperty for better docs
Start server	Call app.listen() after setup

Key Takeaways

Install @nestjs/swagger and swagger-ui-express to enable Swagger in NestJS.

Configure Swagger in main.ts before calling app.listen() for proper docs loading.

Use DocumentBuilder to customize your API documentation details.

Add decorators like @ApiTags and @ApiProperty to enrich Swagger docs.

Access your API docs via the URL path set in SwaggerModule.setup(), commonly '/api'.