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 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, 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.

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.

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