Validación del Especificación OpenAPI Captura de errores en tu archivo Swagger antes de que los clientes se rompan

Un especificación OpenAPI es un contrato entre tu API y todo lo que la consume — clientes generados automáticamente, servidores simulados, documentación y marcos de prueba. El problema es que, a diferencia del código de aplicación, una especificación dañada no lanza una excepción. Produce silenciosamente salida incorrecta en el flujo de trabajo, y la primera vez que lo escuchas es cuando un SDK de cliente genera código inutilizable o tu documentación se renderiza con endpoints faltantes.

Capturar errores de especificación temprano — antes de que lleguen a los consumidores — es la función de la validación de especificación. Este artículo cubre qué validar, dónde se esconden errores comunes y cómo ejecutar la validación localmente y en el navegador.

Por qué la forma de tu especificación importa más allá de la documentación

La mayoría de los desarrolladores piensan en una especificación OpenAPI como un artefacto de documentación — algo que alimenta Swagger UI o Redoc. Eso es solo la mitad de la imagen. La especificación también es la fuente de verdad para:

• Generación de código — Herramientas como openapi-generator y swagger-codegen generan estapas de servidor y bibliotecas de cliente directamente a partir de la especificación. Un esquema malformado produce código malformado.
• Pruebas de contrato — Frameworks como Dredd y Schemathesis prueban tu API en vivo contra su especificación. Una especificación inválida significa que las pruebas no se ejecutan o generan resultados falsos.
• Servidores simulados — Herramientas como Prism y similares sirven respuestas simuladas basadas en los valores de ejemplo y esquemas de tu especificación. Esquemas incorrectos producen simulaciones incorrectas.
• Configuración de gateways — AWS API Gateway, Kong y otros pueden importar especificaciones OpenAPI para configurar rutas, autenticación y validación. Una especificación inválida silenciosamente elimina o configura mal las rutas.

Ninguna de estas herramientas te dirá de forma legible que la especificación está mal. O bien se caerán, producirán basura o omitirán silenciosamente la parte afectada. Validar tu especificación antes de que llegue a estos consumidores es ineludible.

OpenAPI 2.0 vs 3.0 vs 3.1: Las diferencias de versión que confunden a las personas

La versión que declaras al principio de tu especificación cambia las reglas aplicables — y muchos errores surgen de mezclar convenciones entre versiones.

• OpenAPI 2.0 (Swagger) — Usa swagger: "2.0". Los cuerpos de solicitud van a parameters con in: body. Las definiciones viven en definitions, no components/schemas. No tiene soporte para oneOf, anyOf, o not en el nivel de esquema.
• OpenAPI 3.0.x — Usa openapi: "3.0.x". Los cuerpos de solicitud se mueven a requestBody. Los esquemas se consolidan bajo components. Soporta oneOf, anyOf, allOfy not. Añade links y callbacks.
• OpenAPI 3.1.0 — Se alinea completamente con el draft 2020-12 del JSON Schema. nullable es reemplazada por type: [string, null]. exclusiveMinimum/exclusiveMaximum cambio de booleans a números. $schema ahora está permitida en esquemas.

El error de migración más común: copiar una especificación 2.0 y cambiar el campo de versión a 3.0.0 sin mover los cuerpos de solicitud de parameters a requestBody. La especificación parece válida como JSON/YAML pero falla en la validación semántica.

Errores comunes en especificaciones y dónde se esconden

Los errores en especificaciones caen en patrones predecibles. Aquí están los que aparecen con más frecuencia en bases de código real:

Campos requeridos faltantes

Cada operación debe tener al menos una respuesta 2xx definida. Cada parámetro necesita un name y un in valor. Los parámetros de ruta declarados en la URL (por ejemplo, /users/{id}) deben tener un objeto de parámetro correspondiente con in: path y required: true. Faltar cualquier uno de estos produce una especificación técnicamente parseable que falla en validadores y generadores de código en el flujo de trabajo.

Rutas $ref inválidas

A $ref que apuntan a un componente inexistente es uno de los errores más comunes en especificaciones. La referencia parece válida — $ref: "#/components/schemas/UserProfile" — pero el esquema objetivo fue renombrado o eliminado. Los analizadores JSON/YAML aceptan esto sin quejas. Solo un validador de especificaciones lo detecta.

Rutas externas $ref son aún más riesgosas — apuntan a otros archivos o URLs que pueden no ser accesibles en cada entorno. Incluye esas referencias antes de distribuir tu especificación o usarla con herramientas que no resuelvan externos.

Tipos de esquema incorrectos

Los desajustes en los tipos de esquema son sutiles. Declarar type: integer en un campo que devuelve valores de tipo float. Usar format: date-time con un campo que devuelve timestamps en formato Unix (números enteros). Definir un enum con valores que no coinciden con el declarado type. Estos pasan la validación YAML pero producen propiedades mal tipadas en los clientes generados.

Referencias circulares

Un esquema que se referencia a sí mismo — directa o a través de una cadena de $ref valores — causa que los generadores de código y las herramientas de documentación se bloquen o se caigan. La mayoría de los validadores detectan y reportan referencias circulares, pero pueden ser difíciles de desentrañar en esquemas profundamente anidados. La solución es normalmente romper el ciclo con un esquema dedicado para el caso recursivo.

Errores estructurales vs semánticos

Los errores de validación no son todos iguales. Comprender la distinción te ayuda a priorizar los correcciones:

• Errores estructurales — La especificación no cumple con el esquema OpenAPI. Faltan campos obligatorios, los nombres de propiedades son incorrectos o los tipos no coinciden con el formato de la especificación. Estos son capturados por validación estricta de esquema y bloquean la mayoría de las herramientas.
• Errores semánticos — La especificación es estructuralmente válida en JSON/YAML y pasa la validación de esquema, pero describe algo que no puede funcionar. Un punto de entrada con un parámetro de ruta en la URL pero sin definición de parámetro. Un esquema de respuesta que utiliza allOf con campos obligatorios contradictorios. Estos son capturados por reglas de limpieza más profundas, no por verificaciones básicas de esquema.

La mayoría de los validadores en línea y las herramientas de línea de comandos capturan errores estructurales. Capturar errores semánticos requiere un linter basado en reglas, como Spectral, que evalúa la lógica y coherencia interna de la especificación.

componentes/esquemas: Definiciones DRY vs Esquemas en línea

OpenAPI 3.0 introdujo components/schemas como el lugar canónico para definir esquemas reutilizables. El costo:

• Esquemas compartidos en componentes — Correcto cuando el mismo esquema aparece en múltiples lugares (por ejemplo, un User objeto devuelto por varios puntos de entrada). Usar $ref: "#/components/schemas/User" mantiene la especificación DRY y genera una sola clase nombrada en los SDKs de cliente.
• Esquemas en línea — Correcto para formas de respuesta de uso único que son específicas de un único punto de entrada y no se reutilizarán. Incluir en línea evita contaminar components/schemas con definiciones de uso único que hacen que la especificación sea más difícil de leer.

El patrón anti es definir un esquema en components/schemas y luego nunca referenciarlo. Validadores como Spectral pueden detectar componentes no utilizados, lo cual a menudo indica una $ref que se suponía que referenciaba pero que apunta a otro lugar.

requestBody vs parámetros: Dónde ocurren los errores

En OpenAPI 3.0, los cuerpos de solicitud y los parámetros están estrictamente separados:

• parámetros — Para valores de ruta, consulta, cabecera y cookie. Cada parámetro es un valor escalar, no un objeto complejo.
• requestBody — Para el cuerpo de la solicitud (cuerpo JSON, datos de formulario, subidas de archivos). Obligatorio para operaciones POST/PUT/PATCH que aceptan un cuerpo.

El error que confunde a los desarrolladores al migrar de 2.0: en Swagger 2.0, los cuerpos de solicitud eran parámetros con in: body. En OpenAPI 3.0 eso es inválido — in: body no existe. Una especificación con in: body pasa la validación YAML pero falla en la validación de especificación, y los generadores de código o bien fallan o silenciosamente omiten el cuerpo de solicitud.

Cómo validar tu especificación localmente

Tres herramientas sólidas de línea de comandos para validación local, desde la más simple hasta la más exhaustiva:

swagger-cli

Validación estructural rápida y $ref resolución. Útil para una verificación rápida:

npm install -g @apidevtools/swagger-cli
swagger-cli validate openapi.yaml

Reporta errores estructurales y rutas rotas. No detecta problemas semánticos ni de estilo. $ref Redocly CLI

Validación estructural más un conjunto configurable de reglas. Buena rigurosidad por defecto para especificaciones de producción:

Detecta faltas de descripción, referencias rotas y muchos problemas semánticos de forma automática.

npm install -g @redocly/cli
redocly lint openapi.yaml

Spectral

El linter más configurable. Ejecuta el conjunto de reglas de OpenAPI integrado más reglas personalizadas que defines. Ideal para equipos que deseen enforzar guías de estilo internas de API:

Spectral distingue entre errores (que rompen la especificación) y advertencias (problemas de estilo o completitud), así que puedes corregir los problemas bloqueantes primero sin ruido de reglas recomendativas.

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

Validar en tu navegador sin instalar nada

Si quieres validar una especificación rápidamente — sin configurar una línea de comandos ni ejecutar una compilación — el

Validador de especificación OpenAPI / Swagger en iotools.cloud funciona completamente en el navegador. Pega tu especificación en YAML o JSON y te reporta errores estructurales, rutas rotas, campos requeridos faltantes y problemas específicos por versión en OpenAPI 2.0, 3.0 y 3.1. Es útil para una verificación rápida antes de commit, para revisar una especificación que alguien más te envió o para validar una especificación que generaste a partir de anotaciones y que quieres revisar antes de ejecutar generación de código. $ref Integrar la validación en tu flujo de trabajo

Una validación puntual detecta problemas inmediatos pero no previene regresiones. Un enfoque más duradero:

Hook de pre-commit

— Ejecuta

• antes de cada commit. Una especificación dañada nunca llega al repositorio. Paso en la pipeline de CI swagger-cli validate o spectral lint — Añade la validación de especificación como paso temprano en tu pipeline de CI, antes de cualquier paso de generación de código o despliegue que dependa de la especificación.
• Validación de especificación generada — Si generas tu especificación a partir de anotaciones de código (por ejemplo, springdoc, swagger-annotations, FastAPI), valida el resultado generado, no solo las anotaciones. El paso de generación puede producir salida inválida cuando las anotaciones se contradicen o son incompletas.
• El objetivo es hacer que una especificación inválida sea imposible de entregar — no simplemente algo que se arregla cuando un consumidor reporta un problema. Validación de especificación OpenAPI: Detecta errores en tu archivo Swagger antes de que los clientes se rompan 2

Validación de especificación OpenAPI: Detecta errores en tu archivo Swagger antes de que los clientes se rompan 1

También te puede interesar