NestJS Swagger Integration

NestJS Swagger Integration

Document APIs with @ApiProperty, @ApiOperation, @ApiTags, and DocumentBuilder

When to Use

• You need interactive API documentation served at /api (or a custom path)
• You need to document request/response schemas for frontend developers or API consumers
• You want to generate an OpenAPI spec that can be imported into Postman, Insomnia, or API gateways
• You are documenting authentication requirements (Bearer token, API key) on your endpoints

Instructions

1. Install and bootstrap:

npm install @nestjs/swagger swagger-ui-express

// main.ts
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, {
  swaggerOptions: { persistAuthorization: true },
});

2. Annotate controllers:

@ApiTags('users')
@Controller('users')
export class UsersController {
  @ApiOperation({ summary: 'Get a user by ID' })
  @ApiParam({ name: 'id', type: 'string', format: 'uuid' })
  @ApiResponse({ status: 200, type: UserDto })
  @ApiResponse({ status: 404, description: 'User not found' })
  @Get(':id')
  findOne(@Param('id') id: string) { ... }

  @ApiOperation({ summary: 'Create a user' })
  @ApiBody({ type: CreateUserDto })
  @ApiResponse({ status: 201, type: UserDto })
  @ApiBearerAuth()
  @Post()
  create(@Body() dto: CreateUserDto) { ... }
}

3. Annotate DTOs:

export class CreateUserDto {
  @ApiProperty({ example: 'user@example.com', description: 'User email address' })
  @IsEmail()
  email: string;

  @ApiProperty({ example: 'myP@ssw0rd', minLength: 8 })
  @IsString()
  @MinLength(8)
  password: string;

  @ApiPropertyOptional({ example: 'John Doe' })
  @IsOptional()
  @IsString()
  displayName?: string;
}

4. Use mapped types from @nestjs/swagger (not @nestjs/mapped-types) for full Swagger compatibility:

import { PartialType, OmitType, PickType } from '@nestjs/swagger';
export class UpdateUserDto extends PartialType(CreateUserDto) {}
export class UserProfileDto extends OmitType(CreateUserDto, ['password']) {}

5. Document pagination responses:

@ApiResponse({ status: 200, schema: {
  properties: {
    data: { type: 'array', items: { $ref: getSchemaPath(UserDto) } },
    total: { type: 'number' },
    page: { type: 'number' },
  }
}})

Details

@nestjs/swagger uses TypeScript reflection metadata to auto-detect types in DTOs and controllers. When emitDecoratorMetadata is enabled in tsconfig.json (it must be for NestJS to work), most types are inferred automatically.

Enum documentation: Pass enum: MyEnum in @ApiProperty for Swagger to show all valid values: @ApiProperty({ enum: UserRole, enumName: 'UserRole' }).

@ApiHideProperty(): Exclude a property from the Swagger spec (e.g., internal tracking fields) without removing it from the DTO class.

CLI plugin (recommended): Add to nest-cli.json to auto-add @ApiProperty based on class-validator decorators — eliminates duplication:

{
  "compilerOptions": {
    "plugins": ["@nestjs/swagger"]
  }
}

Exclude from production: The Swagger UI and spec endpoint should be conditionally registered. Wrap the SwaggerModule.setup() call: if (process.env.NODE_ENV !== 'production') { ... }.

Export the spec: SwaggerModule.createDocument() returns a plain OpenAPI 3.0 object. Write it to disk with fs.writeFileSync('swagger.json', JSON.stringify(document)) to integrate with API gateway import workflows.

Source

https://docs.nestjs.com/openapi/introduction

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.