¿Cómo generas documentación de API con Swagger?

Question

Accepted Answer

NestJS se integra con **Swagger/OpenAPI** mediante `@nestjs/swagger` para **auto-generar documentación interactiva de API** a partir de tu código — controladores, rutas, DTOs y decoradores. Produce una interfaz navegable donde los desarrolladores pueden explorar y probar endpoints, mantenida sincronizada con el código.

## Por qué es importante

La documentación de API es esencial para cualquier API consumida por otros — equipos de frontend, aplicaciones móviles, integradores de terceros, o incluso tu yo del futuro — y la integración de Swagger de NestJS hace que producir documentos de alta calidad sea notablemente fácil y confiable.

La ventaja clave es que la documentación se **auto-genera a partir del código** (controladores, rutas, DTOs y decoradores), por lo que permanece **sincronizada** con la implementación actual en lugar de desviarse con el tiempo como inevitablemente lo hacen los documentos escritos a mano.

Comprender esto es valioso porque una buena documentación de API mejora dramáticamente la experiencia del desarrollador y reduce la fricción de integración: la **interfaz interactiva de Swagger** permite a los consumidores explorar y *probar* endpoints directamente en el navegador, y la **especificación OpenAPI** generada puede impulsar la generación de SDK de cliente y pruebas de contrato.

Saber cómo configurar Swagger, enriquecer los documentos con decoradores (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`), y documentar la autenticación es un conocimiento práctico y frecuentemente necesario — las APIs bien documentadas son un estándar profesional y un sello de calidad del trabajo de back-end.

Porque NestJS aprovecha su estructura de decoradores/DTOs para generar automáticamente tanto (con esfuerzo mínimo adicional), hay pocas excusas para no tener documentación excelente, convirtiendo esto en una capacidad importante y de alto valor en proyectos reales de NestJS.

```ts
// main.ts
import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";

const config = new DocumentBuilder()
  .setTitle("Users API")
  .setDescription("The users API documentation")
  .setVersion("1.0")
  .addBearerAuth()                       // document JWT auth
  .build();

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup("api/docs", app, document);   // serve the UI at /api/docs
```

Con pocas líneas, Swagger analiza tu aplicación y sirve documentos interactivos en `/api/docs` — reflejando automáticamente tus rutas, parámetros y DTOs.

## Documentando DTOs y respuestas

```ts
export class CreateUserDto {
  @ApiProperty({ example: "ann@example.com", description: "User email" })
  email: string;

@ApiProperty({ minLength: 8 })
  password: string;

@ApiPropertyOptional()                 // optional field in the docs
  age?: number;
}
```

Los decoradores `@ApiProperty` añaden descripciones, ejemplos y restricciones a los campos de DTO, enriqueciendo el esquema generado. (Mucho se infiere automáticamente a partir de tipos de TypeScript y decoradores de `class-validator` — el `plugin CLI` puede reducir incluso este boilerplate.)

## Documentando endpoints

```ts
@ApiTags("users")                        // group endpoints in the UI
@Controller("users")
export class UsersController {
  @Post()
  @ApiOperation({ summary: "Create a user" })
  @ApiResponse({ status: 201, description: "User created", type: User })
  @ApiResponse({ status: 400, description: "Invalid input" })
  create(@Body() dto: CreateUserDto) {}
}
```

Decoradores como `@ApiTags`, `@ApiOperation` y `@ApiResponse` añaden descripciones, agrupan endpoints y documentan posibles respuestas.

## Qué obtienes

```text
✓ Interactive UI (Swagger UI) — browse, read, and TEST endpoints in the browser
✓ Auto-generated, always in sync with the code (no separate doc to maintain)
✓ The OpenAPI spec (JSON) — usable to generate client SDKs, for contract testing, etc.
✓ Request/response schemas, validation rules, auth requirements all documented
```