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 interesarDesestructuración en JavaScript: Simplificando la Asignación de Variables y ObjetosJSDoc 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¿Qué es un Frame en HTML?