Tema 15 · OpenAPI & Swagger

15. Documentación Interactiva y Contratos de API con OpenAPI y Swagger UI

Genera especificaciones OpenAPI 3.0 interactivas mediante JSDoc o esquemas YAML para que desarrolladores frontend prueben la API directamente desde la ruta /api-docs.

Documentación Viva con OpenAPI 3.0 y Swagger

Una API sin documentación precisa o desactualizada frena a cualquier equipo de frontend o integradores móviles. Mediante swagger-ui-express y anotaciones JSDoc con swagger-jsdoc, la documentación se genera a partir del propio código y ofrece una interfaz interactiva tipo "Try it out".

1. Elementos Clave de una Especificación OpenAPI

  • Servers: URLs base según entorno (desarrollo local vs producción en VPS).
  • Components / SecuritySchemes: Declaración del esquema de autenticación bearerAuth con formato JWT.
  • Paths y Responses: Métodos HTTP con descripción de parámetros, esquemas de entrada y posibles códigos de respuesta (200, 201, 400, 401, 404).

⚡ Integración de Swagger UI con Especificación OpenAPI 3.0

Montaje interactivo en la ruta /api-docs con soporte para tokens Bearer JWT.

swaggerConfig.js
Solo lectura
import swaggerUi from 'swagger-ui-express';
import swaggerJsdoc from 'swagger-jsdoc';

// 1. DEFINICIÓN BASE DE LA ESPECIFICACIÓN OPENAPI 3.0
const swaggerOptions = {
  definition: {
    openapi: '3.0.3',
    info: {
      title: 'Kilopolis Academia API',
      version: '1.0.0',
      description: 'API RESTful empresarial construida con Node.js, Express y PostgreSQL.',
      contact: {
        name: 'Soporte de Ingeniería Kilopolis',
        url: 'https://kilopolis.com',
      },
    },
    servers: [
      {
        url: 'https://kilopolis.com/api/v1',
        description: 'Servidor de Producción (VPS)',
      },
      {
        url: 'http://localhost:3000/api/v1',
        description: 'Servidor de Desarrollo Local',
      },
    ],
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT',
          description: 'Introduce tu token de acceso en el formato: Bearer <token>',
        },
      },
    },
    security: [
      {
        bearerAuth: [],
      },
    ],
  },
  // Rutas donde swagger-jsdoc buscará bloques de documentación @openapi
  apis: ['./src/routes/*.js', './src/controllers/*.js'],
};

export const swaggerSpec = swaggerJsdoc(swaggerOptions);

// 2. FUNCIÓN PARA MONTAR SWAGGER EN EXPRESS
export function setupSwagger(app) {
  // Servir el JSON puro de la especificación
  app.get('/api-docs.json', (req, res) => {
    res.setHeader('Content-Type', 'application/json');
    res.send(swaggerSpec);
  });

  // Servir la interfaz interactiva con Swagger UI
  app.use(
    '/api-docs',
    swaggerUi.serve,
    swaggerUi.setup(swaggerSpec, {
      customSiteTitle: 'Documentación Oficial de API · Kilopolis',
      customCss: '.swagger-ui .topbar { display: none }', // Ocultar barra superior verde por defecto
    })
  );
}
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Cuál es el beneficio de definir un securityScheme de tipo bearerAuth en la especificación OpenAPI?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar Express.js: Framework Backend & APIs Empresariales y crear proyectos reales?

Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.