En el desarrollo de aplicaciones web, una buena documentación API es crucial para mantener la claridad y facilitar la colaboración. Swagger-JSDoc es una herramienta poderosa que permite generar documentación Swagger a partir de comentarios JSDoc en tu código JavaScript.
En esta guía, aprenderás qué es Swagger-JSDoc, cómo configurarlo y cómo usarlo para crear documentación API detallada y útil para tus proyectos Node.js.
¿Qué es Swagger-JSDoc?
Swagger-JSDoc es una biblioteca que integra Swagger con JSDoc, permitiendo generar documentación API Swagger automáticamente a partir de los comentarios en el código fuente.
Swagger, ahora conocido como OpenAPI, es un estándar ampliamente utilizado para describir APIs RESTful.
También te puede interesar
JSDoc es una herramienta que genera documentación a partir de comentarios en el código JavaScript. Swagger-JSDoc combina lo mejor de ambos mundos, simplificando la creación y mantenimiento de la documentación API.
Ventajas de Usar Swagger-JSDoc
- Automatización: La documentación se genera automáticamente a partir de los comentarios JSDoc, lo que reduce el esfuerzo manual y asegura que la documentación esté siempre actualizada.
- Estándares Abiertos: Swagger (OpenAPI) es un estándar abierto y bien soportado, lo que facilita la integración con otras herramientas y servicios.
- Interactividad: La documentación generada con Swagger es interactiva, permitiendo a los desarrolladores probar los endpoints directamente desde la interfaz.
Instalación y Configuración de Swagger-JSDoc
Paso 1: Instalación
Primero, debes instalar Swagger-JSDoc en tu proyecto Node.js. Utiliza npm o yarn para añadir la dependencia.
npm install swagger-jsdoc swagger-ui-express --save
Paso 2: Configuración Básica
Después de la instalación, necesitas configurar Swagger-JSDoc en tu aplicación. A continuación, se muestra un ejemplo de cómo hacerlo en una aplicación Express.
const express = require('express');
const swaggerJSDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const app = express();
// Configuración de Swagger-JSDoc
const swaggerDefinition = {
openapi: '3.0.0',
info: {
title: 'Documentación API',
version: '1.0.0',
description: 'Esta es la documentación de la API para mi aplicación',
},
servers: [
{
url: 'http://localhost:3000',
description: 'Servidor de desarrollo',
},
],
};
const options = {
swaggerDefinition,
apis: ['./routes/*.js'], // Ruta a los archivos con comentarios JSDoc
};
const swaggerSpec = swaggerJSDoc(options);
// Configuración de Swagger-UI
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
// Ejemplo de endpoint
app.get('/api/v1/example', (req, res) => {
res.send('Este es un ejemplo de endpoint');
});
app.listen(3000, () => {
console.log('Servidor escuchando en http://localhost:3000');
});
Paso 3: Añadir Comentarios JSDoc
Ahora, añade comentarios JSDoc en tus archivos de rutas para describir los endpoints. Swagger-JSDoc usará estos comentarios para generar la documentación.
/**
* @swagger
* /api/v1/example:
* get:
* summary: Ejemplo de endpoint
* description: Este endpoint devuelve un mensaje de ejemplo.
* responses:
* 200:
* description: Mensaje de éxito
* content:
* application/json:
* schema:
* type: string
* example: Este es un ejemplo de endpoint
*/
app.get('/api/v1/example', (req, res) => {
res.send('Este es un ejemplo de endpoint');
});
Generación de Documentación API
Con Swagger-JSDoc configurado y los comentarios JSDoc añadidos, la documentación API se genera automáticamente. Puedes acceder a ella en tu navegador en la ruta que configuraste para Swagger-UI (/api-docs
en el ejemplo anterior).

Ejemplos Avanzados de Swagger-JSDoc
Documentación de Parámetros
Puedes documentar los parámetros de los endpoints, especificando el tipo de datos, si son requeridos y más.
/**
* @swagger
* /api/v1/users/{userId}:
* get:
* summary: Obtener usuario por ID
* description: Devuelve un usuario basado en su ID.
* parameters:
* - name: userId
* in: path
* required: true
* description: ID del usuario
* schema:
* type: integer
* responses:
* 200:
* description: Información del usuario
* content:
* application/json:
* schema:
* type: object
* properties:
* id:
* type: integer
* example: 1
* name:
* type: string
* example: Juan Pérez
*/
app.get('/api/v1/users/:userId', (req, res) => {
const userId = req.params.userId;
res.json({ id: userId, name: 'Juan Pérez' });
});
Documentación de Cuerpos de Petición
También puedes documentar los cuerpos de las peticiones, especificando los esquemas y ejemplos.
/**
* @swagger
* /api/v1/users:
* post:
* summary: Crear un nuevo usuario
* description: Crea un nuevo usuario con los datos proporcionados.
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* properties:
* name:
* type: string
* example: Juan Pérez
* email:
* type: string
* example: juan.perez@example.com
* responses:
* 201:
* description: Usuario creado exitosamente
* content:
* application/json:
* schema:
* type: object
* properties:
* id:
* type: integer
* example: 1
* name:
* type: string
* example: Juan Pérez
* email:
* type: string
* example: juan.perez@example.com
*/
app.post('/api/v1/users', (req, res) => {
const newUser = { id: 1, name: req.body.name, email: req.body.email };
res.status(201).json(newUser);
});
Swagger-JSDoc es una herramienta esencial para cualquier desarrollador que desee mantener una documentación API clara y actualizada en proyectos Node.js. Al integrar comentarios JSDoc en tu código, puedes generar documentación Swagger automáticamente, lo que facilita la colaboración y mejora la experiencia del desarrollador.
Implementa Swagger-JSDoc en tu próximo proyecto y disfruta de los beneficios de una documentación API bien estructurada y siempre al día.
También te puede interesar