Analizador de calidad de OpenAPI
OpenAPI Linter
Revisa un documento OpenAPI en busca de respuestas que faltan, esquemas sin usar, referencias que no apuntan a nada y los demás defectos que rompen los generadores de código.
Comprueba un documento OpenAPI 3.0 o 3.1 en busca de las cosas que rompen los generadores de código, hacen que las bibliotecas cliente mientan, o que la especificación simplemente exige. Las reglas están escritas a mano y listadas en la página: problemas, no preferencias de estilo.
Documento OpenAPI
Suelta un openapi.yaml
Se lee solo en esta pestaña.
24 hallazgos
errorschema-array-itemscomponents.schemas.Order.items
`type: array` sin `items`.
errorpath-param-undeclaredGET /orders/{orderId}
`{orderId}` en la ruta no está declarado como parámetro.
errorresponse-descriptionGET /orders/{orderId}
La respuesta `200` no tiene description.
errorschema-array-itemsGET /orders/{orderId} responses["200"].content["application/json"].items
`type: array` sin `items`.
errorinfo-missinginfo
No hay `info.version`. Es la versión de la API, no la de OpenAPI.
erroroperation-id-duplicatePOST /orders/{orderId}
El operationId `getOrder` también está en GET /orders/{orderId}.
errorpath-param-requiredPOST /orders/{orderId}
El parámetro `in: path` `id` no tiene `required: true`.
errorpath-param-undeclaredPOST /orders/{orderId}
`{orderId}` en la ruta no está declarado como parámetro.
errorpath-param-unusedPOST /orders/{orderId}
El parámetro `in: path` `id` no aparece en la ruta.
advertenciapath-trailing-slash/orders/
Esta ruta termina en `/`.
advertenciaschema-unusedcomponents.schemas.Customer
Nada referencia este esquema.
advertenciaoperation-id-missingGET /orders/
No hay operationId.
advertenciaresponse-errorGET /orders/
No hay respuesta 4xx.
advertenciadescription-missingGET /orders/{orderId}
No hay ni summary ni description.
advertenciaresponse-errorGET /orders/{orderId}
No hay respuesta 4xx.
advertenciadescription-missingPOST /orders/{orderId}
No hay ni summary ni description.
advertenciaresponse-errorPOST /orders/{orderId}
No hay respuesta 4xx.
advertenciaresponse-successPOST /orders/{orderId}
No hay respuesta 2xx ni 3xx.
notatag-missingGET /orders/
No hay etiqueta.
notatag-missingGET /orders/{orderId}
No hay etiqueta.
notaparameter-descriptionPOST /orders/{orderId}
El parámetro `id` no tiene description.
notaresponse-default-onlyPOST /orders/{orderId}
La única respuesta es `default`.
notatag-missingPOST /orders/{orderId}
No hay etiqueta.
notaservers-missingservers
No hay ningún servidor listado, así que la URL base es `/`.
OpenAPI
3.0.3
Operaciones
3
Errores
9
Advertencias
9
Notas
6
Un conjunto de reglas escrito a mano. Detecta lo que hace tropezar a un generador de código, lo que hace mentir a una biblioteca cliente y lo que la especificación realmente exige — problemas, no preferencias. No carga conjuntos de reglas de Spectral.
Para ver qué cambió entre dos versiones, usa Comparar cambios de OpenAPI.
Cómo se usa
Pega el documento
JSON o YAML, 3.0 o 3.1. Se analiza en esta pestaña; no se sube nada.
Empieza por los errores
Cada hallazgo lleva el id de la regla y la ubicación exacta en el documento. Los errores son cosas que realmente van a salir mal; las advertencias son cosas que normalmente saldrán mal.
Lee la lista de reglas cuando un hallazgo te sorprenda
Cada regla está escrita con su severidad y por qué existe, así que un hallazgo con el que no estás de acuerdo es al menos un argumento que puedes leer.
Preguntas frecuentes
¿Puede cargar mi conjunto de reglas de Spectral?
No. Esto es un conjunto de reglas fijo y escrito a mano, elegido por problemas y no por estilo de la casa. Si tienes una configuración de Spectral, Spectral es la herramienta que la respetará.
No lee mi archivo Swagger 2.0.
Correcto: 2.0 es una forma de documento distinta, no un 3.0 un poco más viejo, y la mitad de las reglas no aplicarían. Conviértelo primero; `swagger2openapi` es la vía habitual.
No siguió mi `$ref` externo.
Un `$ref` dentro del documento se resuelve; uno que apunta a otro archivo significaría descargar desde una ruta que solo tiene tu máquina. Se informa como una nota para que sepas que la comprobación fue incompleta y no limpia.
¿Por qué un `operationId` ausente es una advertencia?
Porque los generadores lo usan para nombrar la función que emiten para esa operación. Sin uno obtienes un nombre derivado de la ruta y el método, que cambia en cuanto cambia la ruta: un renombrado en tu API se convierte en un renombrado en cada cliente.
Puede recibir de
JSON a JSON Schema
JSON to JSON Schema
Deduce un JSON Schema a partir de uno o varios ejemplos, uniendo las formas que encuentra.
Validador de JSON Schema
JSON Schema Validator
Valida un documento contra un JSON Schema e informa de cada fallo con la ruta de la instancia.
curl a código
curl to Code
Convierte un comando curl en fetch, axios, requests de Python, Go, PHP o PowerShell.
Comparar documentos OpenAPI
OpenAPI Diff
Compara dos documentos OpenAPI y separa los cambios que rompen compatibilidad de los que solo añaden.
Después
Estas aceptan lo que produce esta herramienta, así que el resultado puede pasar directamente.
curl a código
curl to Code
Convierte un comando curl en fetch, axios, requests de Python, Go, PHP o PowerShell.
Validador de JSON Schema
JSON Schema Validator
Valida un documento contra un JSON Schema e informa de cada fallo con la ruta de la instancia.
Comparar documentos OpenAPI
OpenAPI Diff
Compara dos documentos OpenAPI y separa los cambios que rompen compatibilidad de los que solo añaden.
Formateador y validador de YAML
YAML Formatter & Validator
Reindenta el YAML de forma uniforme, lo valida y señala los tabuladores y las anclas que rompen los analizadores.
JSON a CSV y de vuelta
JSON ⇄ CSV
Aplana JSON anidado en columnas o reconstruye los objetos desde una tabla, con nombres de columna en notación de puntos.
Comparar dos JSON
JSON Diff
Compara dos documentos JSON por estructura, ignorando el orden de las claves e informando de las rutas añadidas, eliminadas y modificadas.