Documentación automática de APIs con NestJS y Swagger

Curso de NestJS: Programación Modular, Documentación con Swagger y Deploy

Clase 13 de 17

Clase 13 / 17

Recursos

Documentar una API suele percibirse como una tarea tediosa que termina olvidada en un folder estático. Sin embargo, la documentación es un recurso vivo que debe actualizarse conforme evoluciona el sistema. La buena noticia es que NestJS ofrece herramientas para generar documentación automática basada en el estándar OpenAPI, ahorrando trabajo manual y garantizando que los equipos de frontend, aplicaciones móviles o cualquier cliente siempre tengan acceso a información actualizada en un solo endpoint.

¿Qué es la especificación OpenAPI y por qué importa?

La especificación OpenAPI es un estándar diseñado para describir REST APIs de forma legible tanto para humanos como para máquinas. NestJS cuenta con un módulo oficial llamado @nestjs/swagger que permite cumplir con este estándar de manera automática [00:55].

En la documentación oficial de NestJS, dentro del apartado de OpenAPI, se indica que si usas Express como motor HTTP, debes instalar el paquete correspondiente. El proceso es sencillo:

Copiar los paquetes indicados en la documentación.
Ejecutar la instalación desde la terminal.
Configurar el archivo main.ts antes de la llamada a listen.

¿Cómo se configura Swagger en el archivo main.ts?

Toda la configuración ocurre en el archivo main.ts, específicamente antes del método listen [02:15]. Se importan dos elementos principales desde @nestjs/swagger:

DocumentBuilder: permite construir la configuración del documento, donde defines el título de la API, la descripción, la versión y otros metadatos.
SwaggerModule: se encarga de crear el documento y montarlo en una ruta específica.

El endpoint donde se expone la documentación generalmente se configura como /docs en lugar de /api, ya que es la convención más utilizada [03:25]. Una vez configurado, al ejecutar npm run start:dev y visitar la ruta /docs en el navegador, aparecen todos los endpoints autodocumentados sin escribir nada manualmente.

¿Por qué los DTOs aparecen vacíos en la documentación?

Aunque la documentación se genera automáticamente para los controllers, los DTOs (Data Transfer Objects) no se leen de forma automática por el paquete de Swagger [04:30]. Para resolver esto es necesario habilitar el CLI Plugin en el archivo nest-cli.json.

Los pasos son los siguientes:

Agregar la opción compilerOptions en nest-cli.json.
Habilitar el plugin de Swagger dentro de esas opciones.
Cambiar la importación de PartialType: en lugar de obtenerlo desde @nestjs/mapped-types, debe importarse desde @nestjs/swagger [05:40].

Este último punto es fundamental. El PartialType de @nestjs/swagger extiende las mismas funcionalidades pero permite que el plugin lea las propiedades y las refleje en la documentación generada. Cada DTO de update que use PartialType debe actualizarse con esta nueva importación.

¿Qué hacer cuando los cambios en nest-cli.json no se reflejan?

El archivo nest-cli.json no tiene live reload [06:30]. Esto significa que al modificar su configuración, es necesario:

Detener el servidor.
Eliminar la carpeta dist (distribution), donde se generan los archivos estáticos de Swagger.
Volver a ejecutar el proyecto.

Este paso asegura que la documentación se regenere correctamente con la nueva configuración. Una vez completado, al recargar /docs en el navegador, los DTOs aparecerán con todas sus propiedades detalladas, mostrando exactamente qué campos debe enviar quien consuma la API.

¿Qué ventajas ofrece la documentación automática en NestJS?

Con esta configuración, la documentación se crea a medida que escribes código [07:45]. No hay necesidad de mantener archivos de Postman o Insomnia actualizados de forma manual. Los beneficios principales son:

Actualización continua: cada nuevo endpoint aparece automáticamente.
Accesibilidad universal: cualquier equipo o dispositivo con acceso al servidor puede consultar /docs.
Cumplimiento del estándar OpenAPI: la documentación es interoperable con herramientas de terceros.
Reducción del esfuerzo: elimina la documentación manual como cuello de botella.

Además, el paquete de Swagger ofrece decoradores especiales que permiten agregar mayor detalle a cada endpoint, como descripciones, ejemplos de respuesta y agrupación por tags.

Si ya estás construyendo APIs con NestJS, no hay excusa para no entregar documentación profesional. ¿Qué decoradores de Swagger te gustaría explorar para enriquecer aún más tu documentación?