NestJS + Swagger for API Docs

Why Use Swagger with NestJS?

NestJS integrates seamlessly with Swagger (OpenAPI spec) to:

• Auto-generate API documentation
• Provide an interactive UI for testing endpoints
• Document request/response DTOs, headers, and status codes
• Make APIs easier to understand and share

---

Installing Swagger Module

Install the official NestJS Swagger package:

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

---

Setting Up Swagger in main.ts

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

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

  const config = new DocumentBuilder()
    .setTitle('Blog API')
    .setDescription('API docs for the blog platform')
    .setVersion('1.0')
    .addBearerAuth()
    .build();

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

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

Open http://localhost:3000/docs to see it in action.

---

Using Decorators for Auto-Docs

Decorate your DTOs and endpoints to make Swagger smarter:

import { ApiProperty } from '@nestjs/swagger';

export class CreatePostDto {
  @ApiProperty({ example: 'NestJS Guide' })
  title: string;

  @ApiProperty({ example: 'A full tutorial on NestJS.' })
  content: string;
}

In controllers:

@ApiTags('posts')
@Controller('posts')
export class PostsController {
  @Post()
  @ApiCreatedResponse({ description: 'The post has been created.' })
  create(@Body() dto: CreatePostDto) {
    return this.postsService.create(dto);
  }
}

Other useful decorators:

• @ApiQuery()
• @ApiParam()
• @ApiBody()
• @ApiResponse()

---

Customizing Swagger Options

You can:

• Add logo, contact info, servers
• Enable Bearer token auth
• Group endpoints by tags

.setContact('Support', '', 'support@example.com')
.setExternalDoc('Postman Collection', '/docs/postman')
.addServer('http://localhost:3000')

---

Protecting or Versioning the Docs

To version your API docs:

SwaggerModule.setup('docs/v1', app, document);

To protect with a password, wrap the /docs route in a middleware or guard.

---

Summary

• NestJS + Swagger = beautiful, live-updating API docs
• Use decorators like @ApiProperty() and @ApiResponse() for rich documentation
• Customize and protect your docs to suit your needs

> Next: Lesson 15 – Deploying a NestJS App