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

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

Al desarrollar aplicaciones web modernas en Node.js, una de las tareas clave es crear documentación clara y actualizada para la API. Swagger (OpenAPI) es un estándar para describir interfaces RESTful que permite generar automáticamente documentación interactiva, probar solicitudes y mantener contratos entre el cliente y el servidor. En este artículo, analizaremos cómo configurar la generación de documentación Swagger/OpenAPI para aplicaciones Node.js utilizando bibliotecas populares.

¿Qué son Swagger y OpenAPI?

OpenAPI Specification (anteriormente conocido como Swagger Specification) es un estándar formal para describir HTTP API. Permite:

• Definir endpoints, métodos, parámetros y tipos de respuesta.
• Generar automáticamente SDK de cliente.
• Crear documentación interactiva (Swagger UI).
• Validar solicitudes y respuestas.

Para Node.js, existen varias bibliotecas que facilitan la integración de OpenAPI. Consideremos las dos más populares: swagger-jsdoc y swagger-ui-express.

Bibliotecas para generar Swagger en Node.js

Las herramientas principales son:

• swagger-jsdoc — analiza comentarios JSDoc en el código y compila la especificación OpenAPI a partir de ellos.
• swagger-ui-express — muestra la especificación generada como una página web interactiva.
• @nestjs/swagger (si usas NestJS) — decoradores para generación automática.

Nos centraremos en la combinación swagger-jsdoc + swagger-ui-express para Express.js.

Instalación y configuración

Instale los paquetes necesarios a través de npm:

npm install swagger-jsdoc swagger-ui-express

Cree un archivo swagger.js con la configuración básica:

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

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

const swaggerSpec = swaggerJsdoc(options);

module.exports = { swaggerUi, swaggerSpec };

Agregar comentarios JSDoc a los endpoints

Ahora, en sus archivos de rutas (por ejemplo, routes/users.js), agregue comentarios en formato OpenAPI:

/** * @openapi * /users: *   get: *     summary: Obtener lista de usuarios *     tags: [Users] *     parameters: *       - in: query *         name: limit *         schema: *           type: integer *         description: Número de usuarios (por defecto 10) *     responses: *       200: *         description: Lista de usuarios *         content: *           application/json: *             schema: *               type: array *               items: *                 $ref: '#/components/schemas/User' */router.get('/users', async (req, res) => {    const users = await getUsers(req.query.limit || 10);    res.json(users);});

Defina también el modelo de datos:

/** * @openapi * components: *   schemas: *     User: *       type: object *       properties: *         id: *           type: integer *         name: *           type: string *         email: *           type: string */

Conectar Swagger UI a Express

En el archivo principal de la aplicación (app.js o index.js), agregue:

const express = require('express');const { swaggerUi,