Softonic

Validador de specs OpenAPI online

Paso 1 / 2
Siguiente

Pega tu spec de OpenAPI o Swagger arriba para obtener una lista de errores y avisos. Esta página explica qué significa cada mensaje y cómo corregirlo, para pasar de un informe en rojo a uno limpio con rapidez. Los errores hacen que el documento no sea válido; los avisos no.

Cómo comprobar una spec y actuar según el informe

  1. 1

    Pega la spec

    Pega tu documento en JSON o YAML en el campo.

  2. 2

    Abre los resultados

    Continúa al paso de resultados para ver un mensaje de validez o una lista de errores.

  3. 3

    Localiza cada mensaje

    Busca el mensaje en la tabla de abajo y aplica la corrección en tu archivo fuente.

  4. 4

    Pega de nuevo

    Repite hasta que no quede ningún error y decide después qué avisos merece la pena corregir.

Cómo leer los mensajes de error

Mensaje Significado Corrección
No se pudo analizar como JSON ni como YAML. El texto no se puede leer en ninguno de los dos formatos Corrige la sintaxis: comas sobrantes, indentación incorrecta, llaves sin cerrar
Falta el campo de versión ‘openapi’ o ‘swagger’. No hay una clave de versión en el nivel superior Añade openapi: 3.0.3 o swagger: "2.0"
Falta el objeto ‘info’. No hay sección info Añade info con título y versión
info.title es obligatorio. info no tiene título Añade un title bajo info
info.version es obligatorio. info no tiene versión Añade un version bajo info (la versión de tu API)
Falta el objeto ‘paths’. No hay sección paths Añade paths, aunque al principio esté vacío

Los errores son los que deciden si el documento se considera válido. Corrige primero todos ellos.

Cómo leer los avisos

Mensaje Significado Corrección
La ruta ‘x’ debería empezar por ‘/’. Una clave bajo paths no tiene barra inicial Renómbrala a /x
Método desconocido ‘x’ en /ruta. Una clave bajo una ruta no está en la lista conocida Revisa si hay una errata, o ignóralo si es una extensión deliberada o trace

La lista conocida es get, post, put, patch, delete, head, options, parameters, summary, description y servers. Las extensiones de proveedor que empiezan por x- no están en ella, así que también aparecen como avisos.

Lo que una comprobación online no puede detectar

El informe cubre solo la estructura. No sigue los enlaces $ref, no comprueba las definiciones de esquema ni marca los operationId que falten. Considera que un resultado correcto confirma que el archivo tiene la forma de un documento OpenAPI, y usa un linter completo antes de publicar documentación o generar código cliente.

Consejos para revisar un informe largo

Empieza por arriba: un error de análisis significa que nada más es fiable, así que corrígelo antes que nada. Después trata los campos de nivel superior que falten, porque son rápidos de añadir. Solo entonces mira los avisos de rutas. Tras cada ronda de cambios, pega el documento completo y no un fragmento, ya que las comprobaciones necesitan el documento entero para encontrar info y paths. Un informe sin errores y con algunos avisos deliberados es un punto final normal y aceptable.

Preguntas frecuentes

Los errores significan que el documento se considera no válido. Los avisos señalan elementos que conviene revisar, como una ruta sin barra inicial, pero no cambian el resultado de validez.

No necesariamente. Significa que la estructura de nivel superior está bien. Los esquemas, las referencias y las respuestas no se examinan.

Las claves bajo una ruta se comparan con una lista fija de métodos HTTP y de algunos campos de elemento de ruta. Una clave x- no está en ella, así que se marca como aviso. Puedes dejarla tal cual.

No. Siguen el orden de las comprobaciones: primero el campo de versión, después info y por último paths. No hay números de línea.

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

Guías y casos de uso