Generación de Swagger/OpenAPI para JavaScript (Node.js) — herramientas y bibliotecas

Generación de Swagger/OpenAPI para JavaScript (Node.js)

Al desarrollar una REST API en Node.js, una de las tareas clave es crear una documentación clara y actualizada. Swagger (ahora OpenAPI) se ha convertido en el estándar de facto para describir APIs. En este artículo, analizaremos las principales herramientas para la generación automática de la especificación OpenAPI en proyectos de JavaScript (Node.js).

¿Qué es OpenAPI y por qué generarlo?

OpenAPI es una especificación para describir APIs RESTful en formato JSON o YAML. Permite:

• Crear automáticamente documentación interactiva (Swagger UI)
• Generar SDKs de cliente para diferentes lenguajes
• Realizar validación de solicitudes y respuestas
• Simplificar la integración entre equipos

Escribir la especificación manualmente es un proceso laborioso que rápidamente queda obsoleto. Por eso, para Node.js se han desarrollado herramientas que generan OpenAPI a partir del código.

Principales herramientas para generar OpenAPI en Node.js

1. swagger-jsdoc

La biblioteca más popular, que analiza los comentarios JSDoc en el código y los convierte en una especificación OpenAPI. Se instala mediante npm:

npm install swagger-jsdoc swagger-ui-express

Ejemplo de uso con Express:

const swaggerJsdoc = require('swagger-jsdoc');const swaggerUi = require('swagger-ui-express');const express = require('express');const app = express();

const options = {  definition: {    openapi: '3.0.0',    info: {      title: 'Mi API',      version: '1.0.0',      description: 'Ejemplo de API con generación de documentación'    },    servers: [      { url: 'http://localhost:3000' }    ]  },  apis: ['./routes/*.js'] // ruta a los archivos con anotaciones};

const swaggerSpec = swaggerJsdoc(options);app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// Ejemplo de ruta con anotación/** * @openapi * /users: *   get: *     summary: Obtener lista de usuarios *     tags: [Users] *     responses: *       200: *         description: Respuesta exitosa *         content: *           application/json: *             schema: *               type: array *               items: *                 $ref: '#/components/schemas/User' */app.get('/users', (req, res) => {  res.json([{ id: 1, name: 'Iván' }]);});

app.listen(3000);

2. swagger-autogen

Una alternativa más moderna que genera la especificación basándose en anotaciones en los comentarios y determina automáticamente los tipos de datos. Instalación:

npm install swagger-autogen

Ejemplo de script de generación:

const swaggerAutogen = require('swagger-autogen')();

const doc = {  info: {    title: 'Mi API',    description: 'Descripción de la API'  },  host: 'localhost:3000',  schemes: ['http']};

const outputFile = './swagger-output.json';const endpointsFiles = ['./app.js']; // archivo principal con las rutas

swaggerAutogen(outputFile, endpointsFiles, doc).then(() => {  require('./app.js'); // iniciar el servidor después de la generación});

En las rutas, basta con agregar un comentario:

// #swagger.tags = ['Users']// #swagger.description = 'Endpoint para obtener usuarios'app.get('/users', (req, res) => {  // #swagger.responses[200] = { description: 'Lista de usuarios' }  res.json([{ id: 1, name: 'Ana' }]);});

3. express-oas-generator

Biblioteca que intercepta las solicitudes y construye automáticamente la especificación OpenAPI basándose en los datos reales. Adecuada para prototipos:

npm install express-oas-generator

const express = require('express');const expressOasGenerator = require('express-oas-generator');const app = express();

expressOasGenerator.init(app, {}); // inicialización

app.get('/products', (req, res) => {  res.json