Comparar documentos OpenAPI
OpenAPI Diff
Compara dos documentos OpenAPI y separa los cambios que rompen compatibilidad de los que solo añaden.
Compara dos versiones de un documento OpenAPI y separa los cambios en rupturistas y aditivos. La regla que usa está escrita en la página: un cambio es rupturista si una petición que el documento antiguo aceptaba podría ahora rechazarse, o si una respuesta que prometía es una que un cliente existente ya no puede manejar.
Documento anterior
Suelta la versión anterior
Se lee solo en esta pestaña.
Documento nuevo
Suelta la versión nueva
Se lee solo en esta pestaña.
Rompen
8
Aditivos
7
Veredicto
Necesita una versión mayor
GET /pets
- rompeAhora el parámetro `in: query` `limit` es obligatorio.
- agregadoSe agregó un parámetro `in: query` `sort` opcional.
- cambiadoCambió el resumen o la descripción.
GET /pets · responses["200"].content["application/json"]
- rompe`[].id` cambió de tipo: de integer a string.
- rompeLa propiedad `[].name` ahora es opcional.
- rompe`[].status` ganó el valor de enum "pending".
- agregadoSe agregó una propiedad opcional `[].owner`.
GET /pets/{petId} · responses["200"].content["application/json"]
- rompe`id` cambió de tipo: de integer a string.
- rompeLa propiedad `name` ahora es opcional.
- rompe`status` ganó el valor de enum "pending".
- agregadoSe agregó una propiedad opcional `owner`.
GET /pets/{petId}
- rompeLa respuesta `404` desapareció.
DELETE /pets/{petId}
- agregadoSe agregó la operación.
components.schemas.Owner
- agregadoSe agregó el esquema.
info.version
- cambiado`1.0.0` → `2.0.0`
Qué cuenta como ruptura
En una frase: una petición que el documento anterior aceptaba puede quedar rechazada, o una respuesta que prometía es una que un cliente existente ya no puede manejar. Así que: quitar una ruta, una operación, un código de respuesta, un tipo de medio o una propiedad de respuesta; agregar un parámetro obligatorio o una propiedad de petición obligatoria; que algo opcional pase a obligatorio; un cambio de tipo; quitar un valor de un enum de petición; agregar un valor a un enum de respuesta (el switch del cliente no tiene un case para él); y que una propiedad de respuesta pase de obligatoria a opcional. Las direcciones contrarias, y los cambios en descripciones, etiquetas, operationId y marcas de deprecated, son compatibles.
- · Los esquemas se comparan después de seguir los
$refinternos del documento, así que renombrar un componente no es un cambio. Los parámetros de ruta se emparejan por posición y no por nombre. - · Lo que hay dentro de
oneOf·anyOf·notse compara como un todo y se reporta como ruptura si difiere — aquí no se razona sobre ello. - · Un
$refque apunta a otro archivo no se sigue. Junta primero los archivos en uno solo.
Para revisar un solo documento, usa Revisión de OpenAPI.
Cómo se usa
Pon el documento antiguo y el nuevo lado a lado
JSON o YAML para cualquiera de los dos. Ambos se analizan en esta pestaña, así que una especificación sin publicar no sale de tu máquina.
Lee el veredicto
Recuento de rupturistas, recuento de aditivos, y lo que eso significa para el número de versión: un incremento major, uno minor, o nada en absoluto porque el contrato no ha cambiado.
Filtra los rupturistas y léelos
Agrupados por operación, cada uno con lo que cambió. La copia en Markdown tiene la forma de una descripción de pull request.
Preguntas frecuentes
¿Por qué añadir un valor a un enum de respuesta es rupturista?
Porque un cliente existente tiene un switch sin caso para él. Añadir a un enum de *petición* es seguro: el servidor acepta más que antes; añadir a un enum de respuesta envía a los clientes algo de lo que nunca les hablaron. La dirección es lo que lo decide.
Renombré un componente y no informa de ningún cambio.
Correcto. Los esquemas se comparan después de seguir los `$ref`, así que un componente renombrado con la misma forma es el mismo contrato. Los nombres en `components` son internos; los clientes ven la forma resuelta.
¿Una propiedad de respuesta obligatoria que pasa a opcional es rupturista de verdad?
Sí, desde el lado del cliente. Se le prometió que el campo estaría siempre ahí y su código lo lee incondicionalmente; hacerlo opcional significa que el servidor ahora puede omitirlo. Obligatorio y opcional intercambian direcciones entre petición y respuesta, que es la parte que la gente entiende al revés.
¿Cómo maneja `oneOf` y `anyOf`?
Se comparan como un todo y se informan como rupturistas si difieren en algo. Razonar sobre si una unión es superconjunto de otra es un procedimiento de decisión que esto deliberadamente no intenta; un falso «rupturista» que puedes descartar es mejor que un falso «seguro» que no puedes.
Puede recibir de
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.
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.
Probador de rangos semver
Semver Range Tester
Comprueba qué versiones satisfacen un rango, compara dos versiones y ordena una lista por precedencia.
Formateador y validador de JSON
JSON Formatter & Validator
Indenta, minifica y valida JSON, señalando la línea y la columna exactas del error de sintaxis.
Después
Estas aceptan lo que produce esta herramienta, así que el resultado puede pasar directamente.
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.
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.
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.
Probador de rangos semver
Semver Range Tester
Comprueba qué versiones satisfacen un rango, compara dos versiones y ordena una lista por precedencia.
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.
Formateador y validador de JSON
JSON Formatter & Validator
Indenta, minifica y valida JSON, señalando la línea y la columna exactas del error de sintaxis.