Validador de OpenAPI

Sobre el Validador de OpenAPI

La mayoría de equipos generan o escriben a mano un documento OpenAPI y nunca lo pasan por un linter hasta que un SDK cliente se rompe en producción. Esta herramienta te da una primera revisión rápida y totalmente en el navegador: pega tu spec OpenAPI 3.0 o 3.1 en JSON o YAML, o sube tu archivo openapi.yaml / openapi.json, y obtén una verificación estructural, un resumen endpoint por endpoint y una lista priorizada de problemas comunes — operationIds faltantes, parámetros de ruta sin declarar (incluidos los parámetros compartidos a nivel de path item), respuestas 401/403 ausentes en endpoints autenticados, operaciones de escritura sin respuesta 400/422 de validación, objetos de respuesta sin descripción y request bodies sin ejemplos.

También recorre cada $ref del documento y marca como error las referencias locales no resueltas (un #/components/schemas/Foo colgante) más las refs externas/remotas que no puede descargar offline — la mayor causa de fallos en generadores de código y operaciones descartadas en silencio. Tres niveles de rigurosidad para enfocar lo importante según la madurez de tu API: Básica para borradores, Recomendada para revisión de producción y Estricta para specs listas para SDK. Ninguna spec sale de tu navegador.

¿Cómo valido un archivo OpenAPI o Swagger online?

Tres pasos, todo en tu navegador. (1) Pega tu documento OpenAPI 3.0 o 3.1 en el cuadro como JSON o YAML, o sube tu archivo openapi.yaml, openapi.yml u openapi.json con el botón de archivo encima del área de texto. (2) Elige un nivel de rigurosidad — Básica para borradores, Recomendada para revisión de producción, Estricta para specs listas para SDK — y activa las comprobaciones de respuestas auth y ejemplos a tu gusto. (3) Pulsa Validar spec. Obtienes al instante un resumen aprobado/fallido, cuatro estadísticas (paths, operaciones, esquemas, refs resueltas), una tabla de endpoints con métodos y banderas de auth, y una lista de problemas ordenada por severidad (ERROR / AVISO / INFO). Nada se sube a un servidor — el parseo y el lint corren íntegramente en tu máquina, así que es seguro para APIs privadas e internas.

¿Cómo detecta la herramienta referencias $ref rotas o no resueltas?

Recorre todo el documento analizado, recopila cada puntero "$ref" y resuelve cada uno. Los punteros locales como #/components/schemas/Pet se resuelven contra la spec con reglas de JSON-pointer (incluyendo el desescapado ~1 → / y ~0 → ~); si el componente destino no existe, la ref se marca como ERROR — esta es la razón nº1 por la que openapi-generator, oapi-codegen, Kiota, openapi-typescript y Redocly fallan o descartan operaciones en silencio. Las refs externas o remotas (URLs http(s)://, o rutas de archivo como ./common.yaml#/Address) se marcan como AVISO porque esta herramienta offline no puede descargarlas y verificarlas — resuélvelas en CI con Spectral, Redocly CLI o vacuum. La estadística 'Refs resueltas' muestra cuántas referencias locales apuntaban a un componente real, para confirmar de un vistazo que tu grafo de componentes está intacto. Culpables habituales de una ref colgante: un error tipográfico en el nombre del componente, un esquema que renombraste pero olvidaste actualizar, o un $ref a una ruta que vive en otro archivo aún sin empaquetar.

¿Esta herramienta valida contra el esquema JSON completo de OpenAPI 3.1?

No del todo — implementa un subconjunto pragmático centrado en problemas que realmente causan fallos de generación de SDK, documentación rota y huecos de seguridad en producción. Verificamos campos raíz requeridos (versión openapi, info.title, info.version), declaraciones de parámetros de ruta, mayúsculas/minúsculas de métodos HTTP, cobertura de códigos de respuesta, estructura de request body en operaciones de escritura y correlación seguridad/respuestas. Para validación completa contra el meta-esquema oficial, ejecuta en CI herramientas como Spectral, Redocly CLI o vacuum tras este pase en el navegador — descargan el JSON Schema y aplican miles de reglas. La herramienta del navegador es tu revisión diaria; CI es tu puerta.

¿Por qué se marcan 401 y 403 como faltantes si mi endpoint claramente requiere autenticación?

Porque los clientes, generadores de SDK y exploradores de API necesitan formas de respuesta explícitas para manejar errores correctamente. Declarar `security: [{bearerAuth: []}]` indica que se requiere autenticación, pero si solo documentas `200: OK`, el SDK generado no tiene forma tipada para el cuerpo 401 — así que al expirar el token, el cliente lanza un error opaco de parseo en lugar de un AuthError tipado. Añade al menos `401: { description: Token inválido o ausente }` e idealmente un esquema con campos `code` y `message`. Para endpoints con roles (POST/PUT/DELETE/PATCH) añade también 403 Forbidden para distinguir 'no autenticado' de 'permiso incorrecto'. Desactiva la comprobación si gestionas errores de auth uniformemente en un gateway.

¿Cuál es la diferencia entre OpenAPI 3.0 y 3.1 y este validador soporta ambos?

OpenAPI 3.1 alinea el vocabulario con JSON Schema 2020-12: `nullable: true` se reemplaza por `type: [string, null]`, `exclusiveMinimum/Maximum` pasan a números en vez de booleanos, `example` se convierte en `examples` (array), los webhooks son de primera clase y `$ref` puede convivir con keywords hermanas. El validador detecta 3.0.x o 3.1.x por el campo `openapi` y aplica los mismos chequeos estructurales (las reglas se solapan mucho). Si mezclas convenciones — `nullable: true` en una spec `openapi: 3.1.0` — la mayoría de herramientas lo toleran pero la salida del SDK puede sorprenderte. Para repos multi-versión, fija una versión mayor por proyecto.

¿Por qué el parser YAML falla en algunas specs y JSON funciona?

Enviamos un parser YAML deliberadamente pequeño (sin anchors, sin merge keys `<<`, sin tags `!!type`, sin streams multi-documento `---`) para mantener la herramienta offline y ligera. ~95% de specs reales que probamos parsean bien, pero las cargadas de anchors YAML (comunes para deduplicar respuestas compartidas) fallarán. Dos soluciones: (1) convierte YAML a JSON con `npx js-yaml spec.yaml > spec.json` — la expansión de anchors ocurre en conversión; (2) inline los anchors a mano. El mensaje de error apuntará a la línea. Si necesitas soporte YAML completo, usa Spectral o Redocly CLI con js-yaml completo.

¿Qué significa 'parámetro de ruta sin declarar' y por qué rompe clientes?

Cuando tu template de ruta incluye `{petId}` (o cualquier `{nombre}`), cada placeholder debe aparecer en la lista `parameters` de la operación con `in: path` y `required: true`. Si `{petId}` está en la URL pero falta en parameters, generadores como openapi-generator, oapi-codegen, Kiota y openapi-typescript no pueden producir un argumento tipado — saltan la operación, emiten un método sin argumentos con `{petId}` literal en la URL o fallan. El validador detecta ambas direcciones: parámetros en URL pero sin declarar, y declarados pero ausentes en la ruta. Corrige añadiendo las declaraciones que faltan o eliminando obsoletas — la URL es la fuente de verdad.

¿Debe cada operación tener un operationId único y qué convención de nombres es mejor?

Sí — los generadores usan operationId como nombre del método en SDKs cliente. Sin él, sintetizan uno desde método + ruta, produciendo nombres feos e inestables como `getPetsPetId`. Convención: verbo + recurso + cualificador en camelCase: `listPets`, `getPet`, `createPet`, `updatePet`, `deletePet`, `searchPets`, `getPetVaccinations`. Mantén operationIds únicos globalmente (algunos generadores usan namespace por tag, otros no). Para listas paginadas prefiere `listPets` sobre `getPets` para señalar multiplicidad. Para endpoints por lotes usa `bulkCreatePets`. El validador marca operationIds faltantes como WARN — arréglalos antes de que cualquier cliente externo consuma tu spec.

¿Es adecuado para specs OpenAPI generadas por IA (LLMs produciendo definiciones de API)?

Especialmente adecuado. Las specs OpenAPI generadas por LLMs (con prompts tipo 'diseña una API para X') caen consistentemente en los mismos errores: descripciones de respuesta faltantes, parámetros de ruta declarados pero ausentes en URL o viceversa, métodos en minúsculas y mayúsculas mezclados, 401 ausentes en endpoints seguros, request bodies con ejemplos pero sin esquema y respuestas de error olvidadas. Pega la salida del LLM aquí como primera comprobación antes de pasarla a un generador o herramienta de docs. La combinación validación estructural + tabla de endpoints + warnings detecta ~80% de alucinaciones de LLM en pruebas internas con Claude, GPT-4 y Gemini.

¿Soporta Swagger 2.0 o solo OpenAPI 3.x?

Las specs Swagger 2.0 (`swagger: "2.0"` en raíz) se detectan y marcan con recomendación de upgrade — la herramienta no ejecuta reglas de lint sobre ellas. Swagger 2.0 alcanzó freeze de features en 2014 y todo el ecosistema (Spectral, Redocly, Stoplight, Postman, AWS API Gateway, Apigee, Kong) favorece OpenAPI 3.x. Convierte con `swagger2openapi spec.json` (paquete npm) que maneja el 90%+ de la migración automáticamente: tipos `body` van a requestBody, definitions van a components.schemas y `host`/`basePath`/`schemes` colapsan en el array servers. Después de convertir, pega aquí para lintar el resultado antes de mergear.