OpenAPI (Swagger): guía completa y práctica para documentar APIs (con NestJS)

1) Qué es OpenAPI hoy y qué quedó de “Swagger”

OpenAPI es el estándar para describir APIs HTTP de forma legible por humanos y máquinas. Nació como Swagger, pero desde 2015 la especificación vive bajo la OpenAPI Initiative (Linux Foundation); Swagger quedó como ecosistema de herramientas (UI, Editor, etc.). El contrato se escribe en YAML o JSON y sirve para generar docs, tests, clientes/SDKs y más. Swagger+2OpenAPI Initiative+2

A fecha 19 de septiembre de 2025, la versión corriente del estándar es OpenAPI 3.2.0 (publicada en el sitio oficial de especificaciones). Muchas guías y herramientas siguen mostrando o soportando 3.1.x, que alineó OAS con JSON Schema 2020-12 y añadió webhooks, entre otros cambios. Si trabajas en ecosistema mixto, es normal convivir con 3.1.x mientras planificas salto a 3.2.0. OpenAPI Initiative Publications+1

En mi práctica, pasar a un contrato claro nos recortó el lead time de endpoints porque front y back trabajaron en paralelo con mocks; el contrato fue la única fuente de verdad y las breaking changes dejaron de colarse. Esta forma de trabajar se conoce como contract-first y encaja con el enfoque de shift-left testing. Wikipedia

Diferencias de nombres, historia breve y versiones (3.0, 3.1 y 3.2)

• Swagger → nombre histórico y suite de herramientas.

• OpenAPI Specification (OAS) → el estándar.

• Hitos: 3.0 (2017), 3.1 (2021, alineación JSON Schema), 3.2.0 (2025). Wikipedia

2) Por qué adoptar un enfoque contract-first y qué impacto tiene en el equipo

Cuando el contrato va primero, el equipo diseña, revisa y acuerda los modelos y endpoints antes del código. Esto permite:

• Mocks y paralelismo: clientes y testers simulan el servidor temprano.

• Gobernanza: reglas de estilo, linting y validaciones automatizadas.

• SDKs consistentes: menos “parches manuales” en clientes. OpenAPI Initiative

De mi día a día: estandarizamos naming y códigos de error en components y pusimos una prueba de contrato en CI que rompía el build si alguien cambiaba un enum sin changelog. Migrar de 3.0 a 3.1 nos desbloqueó validaciones más expresivas gracias a JSON Schema 2020-12; 3.2 mantiene continuidad con la 3.1, por lo que la adopción es suave si ya estás allí. OpenAPI Initiative Publications

Mocking, paralelismo y shift-left testing con OpenAPI

El valor aparece cuando integras el contrato en tu pipeline: genera mocks desde OAS, corre tests de contrato tempranos y valida que las respuestas reales casan con el esquema. Esto refuerza el shift-left: problemas de diseño se detectan antes del sprint de implementación. Wikipedia

3) OpenAPI con NestJS: de cero a /api en minutos

NestJS ofrece una integración oficial mediante @nestjs/swagger.

1. Instalación

2. Bootstrap (main.ts)

Puntos clave de la doc oficial: createDocument(), setup(), DocumentBuilder para metadatos, opciones avanzadas (SwaggerDocumentOptions, SwaggerCustomOptions) y exposición de /api-json. NestJS Docs

Nota útil: si sirves la UI, el JSON suele quedar en /api-json (Express) o rutas equivalentes en Fastify; útil para versionar el contrato y alimentar codegen/SDKs. Stack Overflow

Instalación y bootstrap con SwaggerModule y DocumentBuilder

DocumentBuilder te da una base conforme a OAS (título, descripción, versión, security schemes). Con SwaggerModule.createDocument agregas rutas y esquemas; con SwaggerModule.setup sirves la interfaz. Truco práctico: define operationIdFactory para IDs estables y así generar SDKs sin renombrados manuales. NestJS Docs

Exposición de /api-json y /api-yaml, y personalización de la UI

Además de la UI, conviene exponer el contrato en crudo (JSON/YAML). Esto alimenta pipelines (SDKs, validadores, linters) y permite fijar una política de versiones. Personaliza la UI (título, temas, persist authorization, doc expansion) desde SwaggerCustomOptions según las necesidades del equipo. NestJS Docs

Opciones avanzadas: SwaggerDocumentOptions, operationIdFactory, autoTagControllers

• SwaggerDocumentOptions: incluir módulos concretos, extraModels, resolución de circular refs.

• operationIdFactory: nombres deterministas para endpoints → SDKs estables.

• autoTagControllers: etiquetas limpias en la UI sin repetición manual. NestJS Docs

4) Buenas prácticas de modelado y organización del contrato

• components como librería: centraliza schemas, responses, parameters, headers y securitySchemes.

• Errores estandarizados: establece un objeto de error común con code, message, details.

• Enums versionados: cualquier cambio de valores va con changelog y checks en CI.

• Naming coherente: kebab para paths, camel para propiedades, Pascal para modelos.

• Licencias/SPDX y webhooks (3.1+): si aplican, decláralos correctamente. Wikipedia

En mi caso, mover todos los esquemas compartidos a components/schemas redujo inconsistencias y desaparecieron los parches ad-hoc en clientes generados.

Aprovechando JSON Schema 2020-12 en OAS 3.1+

Con 3.1, OAS se alinea con JSON Schema 2020-12: puedes usar oneOf, anyOf, nullable como anotación separada, formatos, const, patternProperties, etc., con mayor fidelidad y validadores existentes del ecosistema JSON Schema. Esto eleva la calidad de validación y compatibilidad de herramientas. Wikipedia

5) Seguridad y governance

• Autenticación: define securitySchemes (Bearer/JWT, OAuth2) y aplica security por operación.

• CSP y servidores: si usas Fastify + Helmet, revisa la Content-Security-Policy porque puede bloquear recursos de Swagger UI; ajusta directivas.

• Servidores y entornos: configura servers (dev/stage/prod) para evitar llamadas accidentales.

• Linting y breaking changes: integra Spectral/Zally y diffs de contrato en CI. NestJS Docs

Aprendizaje real: activar Helmet sin ajustar CSP nos “rompió” la UI; bastó permitir script-src y style-src necesarios para la carga segura. NestJS Docs

6) Generación de documentación y SDKs

• Swagger UI: ideal para exploración interactiva.

• Redoc/Redocly: docs estáticas y pulidas para portal público.

• OpenAPI Generator / Swagger Codegen: genera clientes y servidores en docenas de lenguajes; si fijas operationId, tendrás nombres estables en SDKs. También puedes usar servicios como Speakeasy para acelerar SDKs con workflows modernos. Wikipedia+1

Tip operativo: publica el /api-json en artefactos de CI y dispara la generación de SDKs automáticamente tras cada merge a main. Stack Overflow

7) Migraciones y compatibilidad

• 3.0 → 3.1: mayor alineación con JSON Schema 2020-12, webhooks, licencias SPDX.

• 3.1 → 3.2: continuidad; revisa notas de herramientas y plugins antes de subir versión.

• Estrategia: activa validadores para evitar drift entre código y contrato y usa “compat layers” si tu stack aún no soporta todas las novedades. Wikipedia+1

En mi experiencia, con operationIdFactory y reglas de linting el salto fue casi transparente; la clave fue probar codegen en una rama antes de tocar producción. NestJS Docs

8) Errores comunes y cómo evitarlos

• CSP bloqueando Swagger UI → revisa Helmet/headers y permite recursos necesarios. NestJS Docs

• operationId inestable → define una fábrica basada en Controller#method o en verbo + recurso. NestJS Docs

• Drift contrato-código →usa validación en CI y compara respuestas reales vs esquema. OpenAPI Initiative

• Enums “vivos” → versiona cambios y documenta breaking changes.

• Falta de components → duplicación de modelos y errores sutiles.

9) Preguntas frecuentes de OpenAPI (FAQ)

¿OpenAPI y Swagger son lo mismo?
No. Swagger es el nombre histórico y también un conjunto de herramientas. El estándar es OpenAPI Specification bajo la OpenAPI Initiative. OpenAPI Initiative+1

¿Cuál es la versión “más reciente”?
La 3.2.0 (19-sep-2025) en el sitio oficial de especificaciones. Muchas herramientas siguen soportando 3.1.x; revisa compatibilidad antes de migrar. OpenAPI Initiative Publications

¿Cómo integro OpenAPI en NestJS?
Instala @nestjs/swagger, configura DocumentBuilder, genera el documento con createDocument y sirve la UI con setup('/api', ...). Expón /api-json para pipelines. NestJS Docs+1

¿Para qué me sirve JSON Schema 2020-12 en OAS 3.1?
Para expresividad y validaciones más precisas, aprovechando tooling del ecosistema JSON Schema. Wikipedia

Conclusión

OpenAPI te da velocidad, alineación y calidad: un contrato único que enciende mocks, tests, documentación y SDKs. Si trabajas con NestJS, la integración es directa y muy configurable. Mi recomendación: empieza en 3.1 si tu tooling ya lo soporta, planifica el salto a 3.2.0, fija operationId, publica /api-json en CI y blinda tu contrato con linting y breaking-change checks. Con eso, tu documentación dejará de ir detrás del código… y el equipo lo notará en el primer sprint. NestJS Docs+1