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, entornos
• references/decorators.md — Todos los decoradores: @ApiTags, @ApiOperation, @ApiResponse, @ApiProperty
• references/dtos.md — DTOs documentados de los módulos principales de HADA
• references/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/