aibot88 OpenAPI / Swagger en NestJS — Documentación de API HADA
Guía completa para documentar la API REST de HADA con OpenAPI 3.0 y Swagger UI
usando @nestjs/swagger. Cubre configuración, decoradores en controllers y DTOs,
seguridad JWT, y generación del contrato OpenAPI para el equipo de frontend móvil.
Referencias disponibles
references/setup.md— Instalación, SwaggerModule, DocumentBuilder, entornosreferences/decorators.md— Todos los decoradores: @ApiTags, @ApiOperation, @ApiResponse, @ApiPropertyreferences/dtos.md— DTOs documentados de los módulos principales de HADAreferences/security.md— @ApiBearerAuth, esquema JWT en Swagger UI
Cuándo usar cada referencia
| Tarea | Referencia |
|---|---|
| Configurar Swagger por primera vez | setup.md |
| Documentar un controller o endpoint | decorators.md |
| Documentar DTOs de request/response | dtos.md |
| Configurar autenticación JWT en Swagger | security.md |
Reglas críticas (siempre en contexto)
1. Todo endpoint del MVP debe estar documentado — es entregable obligatorio
// ✅ Mínimo requerido por endpoint
@ApiOperation({ summary: 'Reservar un regalo' })
@ApiResponse({ status: 200, type: ReserveGiftResponseDto })
@ApiResponse({ status: 403, description: 'No perteneces al círculo de esta lista' })
@ApiResponse({ status: 409, description: 'El regalo ya está reservado' })
2. Todos los DTOs de respuesta deben tener @ApiProperty en sus campos
// ✅ DTO documentado
export class GiftStatusResponseDto {
@ApiProperty({ example: 'uuid-gift-123' })
giftId: string;
@ApiProperty({ enum: ['AVAILABLE', 'RESERVED', 'RECEIVED'] })
estado: GiftStatus;
// ⚠️ NUNCA añadir reservedById aquí — invariante de privacidad
}
3. @ApiHideProperty para campos que NUNCA deben exponerse en el contrato
export class InternalReservationDto {
@ApiHideProperty() // ← No aparece en Swagger ni en el contrato OpenAPI
reservedById: string;
}
4. Generar el JSON del contrato en CI para que el equipo móvil lo consuma
// scripts/generate-openapi.ts
const app = await NestFactory.create(AppModule);
const document = SwaggerModule.createDocument(app, config);
writeFileSync('./docs/openapi.json', JSON.stringify(document, null, 2));
Fuentes y documentación oficial
- @nestjs/swagger Docs: https://docs.nestjs.com/openapi/introduction
- NestJS OpenAPI — Decorators: https://docs.nestjs.com/openapi/decorators
- NestJS OpenAPI — Types and Parameters: https://docs.nestjs.com/openapi/types-and-parameters
- NestJS OpenAPI — Security: https://docs.nestjs.com/openapi/security
- OpenAPI 3.0 Specification: https://swagger.io/specification/
- Swagger UI: https://swagger.io/tools/swagger-ui/