Validador de OpenAPI 3.1
Pega un documento OpenAPI 3.1 en JSON o YAML para comprobar su estructura de nivel superior. La herramienta busca el campo openapi, un objeto info con title y version, y un objeto paths. Es una comprobación estructural, así que no valida las palabras clave de esquema de 3.1, y algunos patrones compatibles con 3.1 producen un aviso o un error que conviene conocer.
Cómo comprobar un documento 3.1
-
1
Pega tu spec 3.1
Pega el documento con `openapi: 3.1.0` (u otro valor 3.1.x) en el campo, en JSON o YAML.
-
2
Ejecuta la comprobación
Continúa al paso de resultados para ver los errores y los avisos.
-
3
Lee las notas de 3.1
Comprueba si un elemento marcado es un error real o uno de los patrones de 3.1 descritos más abajo.
-
4
Completa con un linter completo
Usa un validador completo de las reglas de JSON Schema 2020-12 cuando la estructura esté limpia.
Qué hace esta herramienta con los archivos 3.1
La versión 3.1 alinea los esquemas con JSON Schema 2020-12. Este validador no lee el interior de los esquemas. Solo inspecciona el nivel superior y las entradas de rutas, así que las funciones de esquema de 3.1, como los arrays de tipos o const, no aprueban ni suspenden aquí. Tampoco se comprueba el valor de la versión en sí: cualquier campo openapi cuenta como presente.
Dos patrones de 3.1 a vigilar
| Patrón en tu archivo 3.1 | Lo que informa la herramienta |
|---|---|
Objeto webhooks y ningún objeto paths |
Error: Falta el objeto ‘paths’. |
Operación trace bajo una ruta |
Aviso: Método desconocido ‘trace’ en la ruta |
$ref como clave en un elemento de ruta |
Aviso: Método desconocido ‘$ref’ en la ruta |
OpenAPI 3.1 permite describir solo webhooks y omitir paths. Esta herramienta exige paths, así que un archivo así se marca con un error aunque la especificación lo permita. Añadir un objeto paths: {} vacío supera la comprobación.
La lista de métodos que se usa aquí es get, post, put, patch, delete, head, options, además de parameters, summary, description y servers. El método trace existe en la especificación, pero no está en esa lista, así que genera un aviso que puedes ignorar si es intencionado. Los avisos no hacen que el documento sea inválido.
Un ejemplo práctico
openapi: 3.1.0
info:
title: Events API
version: 2.0.0
webhooks:
newEvent:
post:
summary: Event delivered
Resultado: un error, “Falta el objeto ‘paths’.” Añade paths: {} y la estructura pasa.
Cuándo usar esto y cuándo ir más allá
Usa esta página para confirmar que un archivo 3.1 tiene la forma correcta antes de abrir una pull request o compartirlo con un socio. Las comprobaciones son rápidas y los mensajes son claros. Una vez que la estructura es correcta, las reglas de esquema 3.1 siguen necesitando un linter completo, porque ahí es donde se esconden la mayoría de los errores reales: declaraciones de tipo no válidas, referencias rotas y definiciones de respuesta que faltan. Considera los dos pasos complementarios, no alternativos.
Si un aviso es intencionado, como trace, anótalo en tu pull request para que los revisores no se pregunten por qué está. Los avisos nunca cambian el resultado válido, así que puedes conservarlos sin problema. Los errores son los elementos que hay que resolver antes de compartir el archivo.
Preguntas frecuentes
No. No mira dentro de los objetos de esquema, así que las palabras clave de JSON Schema 2020-12 no se comprueban. Solo cubre la estructura de nivel superior y las entradas de rutas.
La comprobación exige un objeto paths. Un archivo 3.1 con solo webhooks no lo tiene, así que informa de un error de paths ausente. Añade un paths: {} vacío para superarla.
No. Solo comprueba que exista un campo openapi o swagger, no cuál es su valor.
No necesariamente. trace es una operación válida en la especificación. La herramienta simplemente no la incluye en su lista de métodos conocidos.
Herramientas relacionadas
Generador de Configuración de Webpack
Crea un webpack.config.js para webpack 5 con JavaScript puro, React o Vue: TypeScript, Babel, CSS o Sass, imágenes, HtmlWebpackPlugin, servidor de desarrollo y la línea de npm install.
Convertidor de ASCII a Binario
Convierte cualquier cadena ASCII a su representación binaria. Cada carácter se convierte en ocho bits, separados por espacios, listos para pegar en un seguimiento de protocolo o tarea.
Explorador de Rueda de Color
Explora la rueda de color de forma interactiva. Rota armonías, compara HSL vs RYB, identifica pares complementarios y triádicos en tiempo real.
Validador de URL
Comprueba si una URL tiene una sintaxis válida y descomponla en esquema, host, puerto, ruta, consulta y fragmento, con indicadores de absoluta y HTTPS.
Generador de letras aleatorias
Genera letras aleatorias A-Z. Elige la cantidad, usa mayúsculas, minúsculas o mezcla de ambas, y aplica el resultado en juegos, consignas o clase.
Convertidor de HTML a imagen
Renderiza un fragmento de HTML y CSS como PNG o JPG de tamaño fijo en tu navegador. Elige lienzo y escala, previsualiza y descarga.
Herramienta disponible en otros idiomas
- مدقق OpenAPI 3.1 [AR]
- OpenAPI 3.1 バリデーター [JA]
- OpenAPI 3.1 Validator [DE]
- OpenAPI 3.1-validerare [SV]
- Validador OpenAPI 3.1 [PT]
- OpenAPI 3.1 검증기 [KO]
- Validateur OpenAPI 3.1 [FR]
- OpenAPI 3.1 Validator [NL]
- ตัวตรวจสอบ OpenAPI 3.1 [TH]
- Công cụ kiểm tra OpenAPI 3.1 [VI]
- Walidator OpenAPI 3.1 [PL]
- Validator OpenAPI 3.1 [ID]
- Validatore OpenAPI 3.1 [IT]
- Валидатор OpenAPI 3.1 [RU]
- OpenAPI 3.1 Doğrulayıcı [TR]
- OpenAPI 3.1 验证器 [ZH]
- OpenAPI 3.1 Validator [EN]