nean-api-docs

name	nean-api-docs
description	Generate and serve OpenAPI documentation from NestJS decorators.
argument-hint	[--serve] [--export <path>]
allowed-tools	Bash, Write, Read, Glob, Grep

Purpose

Generate and serve OpenAPI (Swagger) documentation using @nestjs/swagger decorators.

Arguments

• --serve — Ensure Swagger UI is available at /api/docs
• --export <path> — Export OpenAPI spec to file (default: openapi.json)
• (no args) — Audit endpoints for missing documentation

What gets created/updated

apps/api/src/
├── main.ts                     # Swagger setup (if not present)
└── modules/**/
    └── *.controller.ts         # API decorators added
    
openapi.json                    # Generated spec (if --export)

How it works

NestJS Swagger reads decorators from:

1. Controllers — @ApiTags, @ApiOperation, @ApiResponse
2. DTOs — @ApiProperty from class-validator decorators
3. Parameters — @ApiParam, @ApiQuery, @ApiBody

Decorator conventions

Controller decorators

@Controller('users')
@ApiTags('users')
@UseGuards(JwtAuthGuard)
@ApiBearerAuth()
export class UsersController {
  @Get()
  @ApiOperation({ summary: 'List all users' })
  @ApiPaginatedResponse(UserResponseDto)
  findAll(@Query() query: PaginationDto) {}

  @Get(':id')
  @ApiOperation({ summary: 'Get user by ID' })
  @ApiResponse({ status: 200, type: UserResponseDto })
  @ApiResponse({ status: 404, description: 'User not found' })
  findOne(@Param('id', ParseUUIDPipe) id: string) {}

  @Post()
  @ApiOperation({ summary: 'Create new user' })
  @ApiCreatedResponse({ type: UserResponseDto })
  @ApiBadRequestResponse({ description: 'Validation failed' })
  create() {}
}

DTO decorators

export class CreateUserDto {
  @ApiProperty({ 
    description: 'User email address',
    example: '[e-mail]' 
  })
  @IsEmail()
  email: string;

  @ApiProperty({ 
    description: 'Display name',
    minLength: 1,
    maxLength: 100 
  })
  @IsString()
  @MinLength(1)
  @MaxLength(100)
  name: string;

  @ApiPropertyOptional({ 
    description: 'Profile bio',
    default: '' 
  })
  @IsOptional()
  @IsString()
  bio?: string;
}

Swagger setup (main.ts)

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

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

  // Swagger configuration
  const config = new DocumentBuilder()
    .setTitle('My API')
    .setDescription('API documentation')
    .setVersion('1.0')
    .addBearerAuth()
    .addTag('health', 'Health check endpoints')
    .addTag('auth', 'Authentication endpoints')
    .addTag('users', 'User management')
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api/docs', app, document, {
    swaggerOptions: {
      persistAuthorization: true,
    },
  });

  await app.listen(3000);
}

Swagger UI

When configured, Swagger UI is available at /api/docs:

• Interactive API explorer
• Try-it-out functionality (with auth)
• Schema visualization
• Download OpenAPI spec

Audit checklist

When auditing documentation:

• All controllers have @ApiTags
• All endpoints have @ApiOperation with summary
• All response codes documented with @ApiResponse
• All DTOs have @ApiProperty decorators
• Examples provided for complex types
• Auth requirements documented (@ApiBearerAuth)
• Error responses documented

Workflow

1. Ensure @nestjs/swagger is installed
2. Configure Swagger in main.ts
3. Audit controllers for missing decorators
4. Add decorators as needed
5. Verify documentation at /api/docs

Output

• Endpoints documented count
• Missing documentation warnings
• Spec file location (if exported)

Reference

For setup and customization, see reference/nean-api-docs-reference.md