Validador de OpenAPI
Pega o abre un documento OpenAPI 3.0, 3.1 o Swagger 2.0 para comprobarlo contra la estructura de la especificación: campos obligatorios, tipos de valor, propiedades desconocidas, destinos de $ref, parámetros de ruta, operationIds y referencias de seguridad. Cada problema enlaza a su línea, y puedes descargar una copia totalmente desreferenciada.
Última actualización:
Haz clic en un problema para saltar a su línea. Las descargas desreferenciadas insertan cada $ref interna (las referencias recursivas se conservan como $ref). Tu especificación se valida en tu navegador y nunca se sube.
Cómo usar Validador de OpenAPI
- Pega tu especificación en el editor, abre un archivo .yaml o .json, o carga un ejemplo.
- Lee el resumen: una marca verde significa que no hay errores; si no, se muestra el número de errores, avisos y notas.
- Haz clic en un problema para saltar a su línea en el editor, corrígelo y observa cómo se actualiza la lista mientras escribes.
- Filtra por errores, avisos o notas para centrarte primero en lo que bloquea la generación de código.
- Exporta un informe de texto, o descarga una copia JSON/YAML desreferenciada con todas las $ref internas insertadas.
Errores de validación de OpenAPI más comunes y cómo corregirlos
| Mensaje | Causa típica | Solución |
|---|---|---|
| falta la propiedad obligatoria "description" (respuesta) | Respuestas escritas como 200: {content: …} | Añade description: a cada respuesta; puede ser una frase corta. |
| no declara el parámetro de ruta | Ruta /users/{id} sin un parámetro correspondiente | Añade name: id, in: path, required: true con un esquema, a nivel de ruta o de operación. |
| El parámetro de ruta debe tener required: true | required omitido (por defecto es false) | Los parámetros de ruta siempre son obligatorios: pon required: true. |
| Referencia rota | Error tipográfico o sección incorrecta en $ref | Usa el nombre sugerido; 3.x usa #/components/schemas/X y 2.0 usa #/definitions/X. |
| debe ser una cadena, se encontró un número | version: 1.0 u openapi: 3.0 sin comillas | Pon el valor entre comillas: "1.0", o usa una versión completa como 3.0.3. |
| Propiedad desconocida / palabra clave de esquema desconocida | Errores tipográficos (maxLenght), palabras clave de 3.1 en 3.0, o campos personalizados | Corrige la ortografía o añade el prefijo x- a los campos personalizados. |
| operationId duplicado | Operaciones copiadas y pegadas | Da a cada operación un ID único en camelCase; los generadores de código lo convierten en un nombre de método. |
| El esquema de seguridad no está definido | El nombre en security difiere del de securitySchemes | Usa exactamente la clave definida en components.securitySchemes. |
OpenAPI 3.0 vs 3.1 vs Swagger 2.0: reglas que cambian
| Tema | Swagger 2.0 | OpenAPI 3.0 | OpenAPI 3.1 |
|---|---|---|---|
| Campo de versión | swagger: "2.0" | openapi: 3.0.x | openapi: 3.1.x |
| Esquemas reutilizables | definitions | components/schemas | components/schemas |
| Cuerpo de la petición | Parámetros in: body / formData | requestBody | requestBody |
| Valores nulos | no admitido (x-nullable) | nullable: true | type: [string, "null"] |
paths | obligatorio | obligatorio | opcional si existen components o webhooks |
Propiedades junto a $ref | ignoradas | ignoradas | permitidas en esquemas; summary/description en otros lugares |
| Ejemplos en esquemas | example | example | Se prefiere examples (array) |
exclusiveMinimum | booleano | booleano | número |
¿Quieres explorar la documentación cuando la especificación sea válida? Ábrela en el Visor de OpenAPI, o edítala con vista previa en vivo en el Editor de OpenAPI.
Preguntas frecuentes
¿Qué diferencia hay entre errores, avisos y notas?
Los errores incumplen la especificación: herramientas como los generadores de código, Swagger UI o los gateways de API pueden rechazar el archivo o comportarse de forma impredecible. Los avisos son válidos pero casi con seguridad son equivocaciones, como una propiedad obligatoria que no está definida. Las notas son sugerencias de limpieza, como componentes sin usar o etiquetas que faltan en la lista de nivel superior.
¿Qué versiones de OpenAPI se admiten?
OpenAPI 3.0.x, OpenAPI 3.1.x y Swagger 2.0 (OpenAPI 2.0). El campo de versión decide qué reglas se aplican: por ejemplo, nullable y exclusiveMinimum booleano son funciones de 3.0, mientras que type: [string, 'null'], const y los esquemas booleanos son solo de 3.1.
¿Por qué "version: 1.0" aparece como error?
En YAML un 1.0 sin comillas es un número, pero info.version debe ser una cadena. Escribe version: "1.0" o 1.0.0. Lo mismo ocurre con openapi: 3.0, que debe ser la versión completa entre comillas, como 3.0.3, y con códigos de respuesta como 200, que deberían ser claves entre comillas.
¿Resuelve archivos $ref externos?
No. Las referencias dentro del documento (#/components/…) se resuelven y se comprueban. Las referencias a otros archivos o URL se muestran como notas porque el navegador no puede leer tus otros archivos; empaquétalos primero o pega una especificación de un solo archivo.
¿Qué hace «Descargar desreferenciado»?
Sustituye cada $ref interna por una copia del objeto al que apunta, y produce un documento autónomo que algunas herramientas necesitan. Las referencias que apuntan a sí mismas (esquemas recursivos) no se pueden insertar y se conservan como $ref.
¿Es lo mismo que validar contra el JSON Schema oficial?
Comprueba las mismas reglas estructurales que los JSON Schemas oficiales de OpenAPI (campos obligatorios, tipos, propiedades permitidas y patrones) y añade comprobaciones semánticas que los esquemas no pueden expresar, como que los parámetros de ruta coincidan con la plantilla, operationIds únicos y $refs resolubles. Los mensajes de error señalan la línea exacta en lugar de una ruta del esquema.
¿Se sube mi especificación de API a algún sitio?
No. El análisis y la validación se ejecutan totalmente en tu navegador. Solo se carga desde una CDN el analizador de código abierto js-yaml para leer YAML; tu especificación nunca sale de tu dispositivo.
¿Se prueban todas las herramientas de FreeToolCabin para comprobar su calidad y precisión?
Sí. Cada herramienta del sitio pasa pruebas automáticas en navegadores reales para comprobar que el resultado es correcto y que no hay errores. Si encuentras un fallo o tienes una sugerencia, escríbenos a [email protected] y lo revisaremos.