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
bearerAuthcon 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.
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¿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.