La documentación de APIs REST es una tarea esencial para garantizar que otros desarrolladores puedan consumir y comprender el funcionamiento de nuestras APIs. Una buena documentación no solo es un signo de profesionalismo, sino también una herramienta poderosa para optimizar la colaboración y la eficiencia.

Vamos a aprender a documentar una API REST creada en Node.js utilizando las herramientas Swagger Autogen y Swagger UI Express. Además, exploraremos las ventajas que estas herramientas ofrecen para facilitar el desarrollo y el consumo de APIs.

¿Qué es Swagger?

Swagger es un conjunto de herramientas para definir y documentar APIs REST bajo el estándar OpenAPI. Es importante destacar que Swagger no está ligado a un lenguaje de programación específico, sino que su objetivo principal es describir de manera clara cómo interactuar con los servicios de una API. Con Swagger, es posible crear documentación interactiva que permite a los desarrolladores explorar y probar los endpoints directamente desde el navegador.

Nota: Aunque Swagger facilita la visualización y uso de la documentación, no genera automáticamente el archivo de especificación de la API. Este trabajo es realizado por herramientas como Swagger Autogen, que automatiza la creación de dicho archivo JSON o YAML.

Ventajas de usar Swagger y Swagger Autogen

  1. Automatización del proceso de documentación
    Con Swagger Autogen, puedes generar el archivo de especificación a partir de tu código, reduciendo la carga manual y garantizando que siempre esté actualizado.
  2. Interfaz interactiva con Swagger UI Express
    La integración con Swagger UI Express permite visualizar y probar los endpoints de manera fácil y amigable.
  3. Estandarización y compatibilidad
    Al seguir el estándar OpenAPI, las APIs documentadas con Swagger son fácilmente entendibles por otros desarrolladores y herramientas.
  4. Reducción de Errores y Mejor Colaboración
    La sincronización entre código y documentación minimiza malentendidos y agiliza la colaboración entre equipos.
  5. Experiencia mejorada para consumidores
    Los desarrolladores que consumen tu API pueden integrarse más rápido gracias a la claridad y accesibilidad de la documentación.

Cómo documentar tu API REST con Swagger Autogen y Swagger UI Express

1. Preparación del proyecto

Inicia un proyecto Node.js
Si aún no tienes un proyecto, inicialízalo con:

npm init -y

Instala las dependencias necesarias
Usa los siguientes comandos para instalar las herramientas requeridas:

npm install swagger-ui-express npm install --save-dev swagger-autogen

2. Configuración de Swagger Autogen

Crea el Archivo de Configuración
Añade un archivo swagger.js en el directorio raíz con el siguiente contenido:

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

const doc = {
    info: {
        title: 'API de Mascotas',
        description: 'Documentación de la API para la gestión de mascotas',
    },
    host: 'localhost:3000',
    schemes: ['http'],
};

const outputFile = './swagger_output.json';
const endpointsFiles = ['./index.js']; // Cambia este archivo según el punto de entrada de tu API

swaggerAutogen(outputFile, endpointsFiles).then(() => {
    require('./index'); // Inicia el servidor automáticamente
});

En el script anterior, importamos el paquete swagger-autogen y definimos las configuraciones necesarias para realizar la construcción del archivo .json necesario para mostrar la documentación.

Ejecuta el script de generación
Ejecuta el siguiente comando para generar el archivo JSON de especificación:bashCopiar códigonode swagger.js

Esto creará un archivo llamado swagger_output.json que contiene la descripción de los endpoints de tu API. Este archivo será usado por el paquete swagger-ui-express.

3. Integración con Swagger UI Express

Configura la ruta de documentación
Modifica el archivo principal de tu API (index.js) para incluir el middleware de Swagger UI Express:

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerFile = require('./swagger_output.json');

const app = express();

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerFile));

app.listen(3000, () => {
    console.log('Servidor corriendo en http://localhost:3000');
});
  1. Accede a la documentación
    Inicia tu servidor y abre un navegador en http://localhost:3000/api-docs para explorar los endpoints de tu API a través de la interfaz interactiva.

Swagger Autogen, hace una lectura del código, luego lo verifica y a partir del él va a generar todo lo necesario.

Importante cuando uses métodos que requieren o usan el payload (req.body) haz la desestructuración que swagger autogen, va a incluir esta definición en la llamada o uso del endpoint respectivo.

Si deseas personalizar o complementar la documentación, puedes agregar comentarios en el controller de forma que swagger autogen los tome en cuenta.  

Ejemplo de código documentado

El uso de comentarios en tus controladores puede mejorar la documentación generada. Por ejemplo:

/**
 * @route GET /pets
 * @description Obtiene una lista de mascotas
 * @response 200 - Lista de mascotas
 */
app.get('/pets', (req, res) => {
    res.send([{ id: 1, name: 'Fido' }, { id: 2, name: 'Luna' }]);
});

Swagger Autogen extraerá estos comentarios para enriquecer la especificación de tu API.

El uso de Swagger Autogen y Swagger UI Express transforma la documentación de APIs REST en un proceso eficiente y profesional. Estas herramientas no solo automatizan tareas tediosas, sino que también proporcionan una experiencia superior para los consumidores de la API, quienes pueden explorar y probar los servicios de manera intuitiva.

Implementar Swagger en tus proyectos garantiza una documentación clara, estandarizada y accesible, facilitando la colaboración entre equipos y mejorando la percepción de calidad de tu API.

En este contenido, realizamos la implementación de la documentación de una API real, donde hacemos el paso a paso y obtenemos el swagger a partir de la ejecución de lo descrito anteriormente.