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

Contenido del curso

Fundamentos y Primer CRUD

Base de Datos y Persistencia con TypeORM

Autenticación y Autorización

Tu API Completa

Tomar examen

Cursos Empresas Blog Live Conf Eventos Precios

0:0015:58

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

Curso de Backend con NestJS

Clase 32 de 35

Clase 32 / 35

Recursos

La correcta documentación de APIs es esencial para cualquier proyecto moderno. Ayuda a asegurar que cualquier cliente —ya sea una aplicación web, móvil o de escritorio— pueda comprender y usar los diferentes métodos de tu sistema. Con NestJS y el módulo Swagger, este proceso se vuelve automático y mucho más sencillo de mantener.

¿Por qué utilizar documentación autogenerada en NestJS?

Autogenerar la documentación con Swagger en NestJS mejora la comunicación entre equipos y facilita la integración de clientes externos. El estándar Open API define cómo documentar una application programming interface, entregando una estructura clara y fácil de explorar. Así, desarrolladores pueden descubrir rápidamente los endpoints y las formas correctas de interactuar con ellos, evitando malentendidos y errores comunes.

¿Cómo instalar y configurar Swagger en NestJS según el estándar Open API?

La integración parte instalando un paquete de Swagger para NestJS desde la terminal. Luego, debes: - Copiar la configuración sugerida en la documentación oficial e integrarla en tu archivo principal. - Asignar detalles como título, descripción y versión del API en el document builder provisto por el paquete. - Exponer el endpoint de Swagger, idealmente bajo /docs, y configurar un endpoint adicional /swagger.json para proveer la documentación en formato JSON.

Esto permite que cualquier interesado explore todos los endpoints a través del navegador y descargue especificaciones compatibles con herramientas de inteligencia artificial o generadores de código frontend.

¿Cómo agregar ejemplos y descripciones detalladas para los endpoints con DTOs y decoradores?

Los DTOs son clave para enriquecer la documentación técnica. Añade decoradores como ApiProperty a cada propiedad de tus DTOs (por ejemplo, sobre campos como title, content, categoryIds). Esto permite que los consumidores vean ejemplos claros sobre cómo deben estructurar sus peticiones y respuestas.

Para casos como el método update, donde se utiliza PartialType, debes importar la versión correspondiente de Swagger para que los campos se documenten correctamente, evitando inconsistencias.

¿Qué prácticas ayudan a documentar cada endpoint y su respuesta?

Utiliza el decorador ApiOperation para dar una descripción clara de la función de cada ruta (crear, actualizar, eliminar o listar posts).
Emplea ApiResponse para definir los posibles códigos de estado y tipos de datos que cada endpoint devuelve. Así, los consumidores entienden el resultado esperado con mayor precisión.
Resuelve posibles conflictos de nombres importando las entidades con alias, lo que facilita especificar tipos en las respuestas de Swagger sin ambigüedades.

Al documentar las entidades (por ejemplo, dando ApiProperty a todas las columnas no relacionadas), asegúrate de evitar conflictos o referencias circulares, limitando temporalmente los decoradores a las propiedades más importantes.

¿Cómo ayuda esta documentación autogenerada a la integración con IA y otras herramientas?

El endpoint JSON no solo sirve para humanos, sino también para servicios automáticos y motores de inteligencia artificial. Si envías la documentación generada por Swagger a una IA, puede ayudarte a crear clientes de tu API en frameworks como React o Angular. Incluso, agentes automáticos pueden identificar qué endpoints deben usar según las descripciones y tipos definidos, agilizando flujos de desarrollo y pruebas.

¿Has implementado documentación Swagger en tus proyectos NestJS? Comparte qué desafíos encontraste o qué beneficios inmediatos observaste al conectar clientes externos a tu API.

if(nodeEnv === "development" || nodeEnv === "dev"){
    const config = new DocumentBuilder()
      .setTitle("Post example")
      .setDescription("The Post api description")
      .setVersion('1.0')
      .build();
    const documentFactory = () => SwaggerModule.createDocument(app, config);
    SwaggerModule.setup('docs', app, documentFactory, {
      jsonDocumentUrl: 'swagger/json',
    })
  }

Resumen

¿Por qué utilizar documentación autogenerada en NestJS?

¿Cómo instalar y configurar Swagger en NestJS según el estándar Open API?

¿Cómo agregar ejemplos y descripciones detalladas para los endpoints con DTOs y decoradores?

Para casos como el método update, donde se utiliza PartialType, debes importar la versión correspondiente de Swagger para que los campos se documenten correctamente, evitando inconsistencias.

¿Qué prácticas ayudan a documentar cada endpoint y su respuesta?

Utiliza el decorador ApiOperation para dar una descripción clara de la función de cada ruta (crear, actualizar, eliminar o listar posts).
Emplea ApiResponse para definir los posibles códigos de estado y tipos de datos que cada endpoint devuelve. Así, los consumidores entienden el resultado esperado con mayor precisión.
Resuelve posibles conflictos de nombres importando las entidades con alias, lo que facilita especificar tipos en las respuestas de Swagger sin ambigüedades.

¿Cómo ayuda esta documentación autogenerada a la integración con IA y otras herramientas?

¿Has implementado documentación Swagger en tus proyectos NestJS? Comparte qué desafíos encontraste o qué beneficios inmediatos observaste al conectar clientes externos a tu API.

Comentarios (2)2 comentarios

Erick Bejarano

Hace un año

No es inseguro tener la descripcion de que endpoints tiene mi api?

Alexander Oses

Como suele ser, depende: si la aplicación es solo de consumo a clientes finales, no tienes para qué exponer tu api con Swagger. Pero por otra parte, si trabajas con más desarrolladores, o expones tu api para que cualquier programador pueda usarla: al desarrollador que tenga que comunicarse con tu api le va a servir la documentación de swagger que se está enseñando aquí.

En varios empleos trabajas con más desarrolladores en tu equipo, alguien encargado del frontend por ejemplo, por lo tanto, solo necesitarías exponer la documentación de swagger en ambiente de desarrollo. Para este fin, podrías exponerla con un if solo si se está en ambiente de desarrollo:

Daniel Alexander Muelas Rivera

Que buena pregunta y que buena respuesta, estaba pensando justamente lo mismo.

Frederic Soc Morales

Hace 10 meses

Esto es muy útil para personas que no nos gusta documentar 😅 increible!! 🔥🚀

Fundamentos y Primer CRUD

Crea una API RESTful con NestJS

Instalación del CLI de NestJS y primer proyecto con API

Creación de endpoints dinámicos para consultar usuarios en NestJS

Operaciones CRUD en APIs REST con Postman

Método PUT para actualizar usuarios con ID automático

Manejo de status codes HTTP en NestJS

DTOs y validación automática de datos en APIs con NestJS

Servicios y lógica de negocio en NestJS

Variables de entorno seguras en NestJS

Programación modular en NestJS con UserModule

Base de Datos y Persistencia con TypeORM

Configuración de PostgreSQL con Docker y Docker Compose

Configuración de PostgreSQL con TypeORM en aplicaciones NestJS

Creación de entidades ORM con decoradores en TypeScript

Repository Pattern con TypeORM en NestJS

Relaciones uno a uno entre usuarios y perfiles en PostgreSQL

Actualización de DTOs con mapped types en NestJS para perfil y usuario

Generación automática de módulos CRUD con NestJS y AI

Relación uno a muchos con TypeORM

CRUD de categorías con IA en NestJS

Relaciones many-to-many con TypeORM y validación de arrays

Reutilización de servicios entre módulos en NestJS

Migraciones en TypeORM sin perder datos

Cómo evitar perder datos al migrar columnas

Autenticación y Autorización

Hashing de contraseñas con Bcrypt en NestJS

Excluir campos sensibles con ClassTransformer

Autenticación local con Passport en NestJS

Endpoint de login con Passport en NestJS

Implementación de JSON Web Token para autenticación en NestJS

Rutas protegidas con JWT en NestJS

User ID automático desde JWT en NestJS

Tu API Completa

Autogenera resúmenes e imágenes con OpenAI en NestJS

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

Preparar tu API NestJS para producción

Desplegar aplicación Node.js a producción con Railway y PostgreSQL

Desarrollo de API REST escalable con NestJS en producción

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