Swagger / OpenAPI Docs

The @nestjs/swagger package generates interactive API documentation from your code.

SyntaxSwaggerModule.setup('docs', app, document)

Swagger (OpenAPI) produces interactive documentation for your API. The @nestjs/swagger package builds it automatically from your controllers and DTOs.

Setup

  1. Build a document with DocumentBuilder in main.ts.
  2. Call SwaggerModule.setup('docs', app, document).
  3. Visit /docs to explore and test endpoints in the browser.

Decorators like @ApiTags() and @ApiProperty() enrich the generated docs.

Example

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

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

  const config = new DocumentBuilder()
    .setTitle('Products API')
    .setVersion('1.0')
    .build();

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

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

When to use it

  • A developer adds @nestjs/swagger to auto-generate interactive API docs at /api so front-end teams can explore and test endpoints without asking the backend team.
  • A team uses @ApiProperty() on DTO fields so the Swagger UI shows the correct types and example values for each request body.
  • An engineer uses @ApiBearerAuth() on a controller so the Swagger UI includes an Authorize button for JWT-protected routes.

More examples

Set up Swagger in main.ts

Adds Swagger to the app at the /api path using DocumentBuilder to define the title, description, version, and Bearer auth scheme.

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

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const config = new DocumentBuilder()
    .setTitle('My API')
    .setDescription('REST API documentation')
    .setVersion('1.0')
    .addBearerAuth()
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);
  await app.listen(3000);
}

@ApiProperty on DTO

Decorates DTO fields with @ApiProperty so Swagger generates an accurate schema with example values for the request body.

Example · ts
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';

export class CreateProductDto {
  @ApiProperty({ example: 'Laptop', description: 'Product name' })
  name: string;

  @ApiProperty({ example: 999.99 })
  price: number;

  @ApiPropertyOptional({ example: 'Electronics' })
  category?: string;
}

@ApiTags and @ApiBearerAuth

Tags the controller for grouping in the Swagger UI, marks it as Bearer-auth-required, and adds an operation summary.

Example · ts
import { Controller, Get } from '@nestjs/common';
import { ApiTags, ApiBearerAuth, ApiOperation } from '@nestjs/swagger';

@ApiTags('products')        // groups route under 'products' in Swagger UI
@ApiBearerAuth()            // shows lock icon for JWT-protected routes
@Controller('products')
export class ProductsController {
  @Get()
  @ApiOperation({ summary: 'List all products' })
  findAll() { return []; }
}

Related

nest versioningnest dtos

Discussion

  • Be the first to comment on this lesson.