Validador OpenAPI y Swagger

Una descripción OpenAPI sirve de contrato entre quienes desarrollan, documentan y consumen una API. Una sangría YAML incorrecta, un campo obligatorio ausente o una referencia sin resolver pueden impedir su uso. Este validador ayuda a localizar esos errores en JSON o YAML, directamente en tu navegador. Admite Swagger 2.0, OpenAPI 3.0.0–3.0.4 y OpenAPI 3.1.0–3.1.2, con el alcance indicado en el informe.

La comprobación empieza por la sintaxis: el texto debe poder interpretarse como un único documento JSON o YAML, sin claves duplicadas. Después se comprueban la versión y la estructura esperada, incluidas la información de la API y sus operaciones. Un archivo sintácticamente correcto puede incumplir el esquema OpenAPI de su versión.

Las referencias internas usan JSON Pointer, por ejemplo #/components/responses/Ok, para señalar ubicaciones del mismo documento. El validador comprueba su resolución y distingue las referencias reales de las claves $ref incluidas en los datos de un ejemplo. Rechaza las referencias a otros archivos o esquemas remotos; ningún resolutor los descarga.

Las comprobaciones adicionales cubren los operationId de rutas y webhooks, los parámetros de ruta y los tipos de palabras clave de los esquemas 3.1. Un resultado correcto sigue siendo parcial: no comprueba todas las restricciones semánticas, los formatos ni la validez de los ejemplos. Los dialectos personalizados, $id, anclas y referencias dinámicas se indican como no admitidos.

Una ruta de diagnóstico como /paths/~1health/get/responses señala el campo responses de GET /health: en JSON Pointer, ~1 representa una barra oblicua. Se muestra una línea cuando puede localizarse en el texto fuente. Empieza por la primera causa clara antes de abordar los diagnósticos secundarios del mismo objeto incompleto.