Pega las definiciones anterior y nueva para generar el informe. Confirma el impacto en clientes con pruebas de contrato; no se recuperan referencias externas.
Se ejecuta localmente en tu navegadorLas etiquetas de cambio incompatible se centran en operaciones o respuestas eliminadas y entradas que pasan a ser obligatorias. Los cambios de esquema se marcan para revisión porque su compatibilidad depende de los clientes.
Usa este diff para una revisión rápida del contrato y confirma después el impacto en consumidores mediante pruebas de API versionadas. El comprobador local no resuelve referencias externas ni archivos remotos.
Pega la especificación publicada en «Earlier specification» y la propuesta en «Updated specification», y pulsa el botón de comparación. Ambas casillas aceptan JSON o YAML, y los dos documentos permanecen en el navegador: no se sube, ni se descarga, ni se ejecuta nada.
El resultado es un informe de revisión agrupado por gravedad, con un JSON Pointer en cada entrada, de modo que cada hallazgo se puede rastrear hasta el punto exacto del documento nuevo.
Una operación eliminada, un parámetro obligatorio eliminado, un parámetro opcional que pasa a obligatorio, un parámetro nuevo obligatorio y un cuerpo de petición que ahora es obligatorio se listan como DANGER. También un código de respuesta eliminado y un tipo de contenido de petición eliminado, porque los clientes existentes pueden depender de ellos.
Los cambios de esquema se informan como WARNING y no como DANGER, porque si rompen un cliente depende del cliente: esquemas de parámetro, de petición y de respuesta modificados, esquemas de componente eliminados o editados, y parámetros opcionales eliminados. Editar un componente compartido se informa en /components/schemas/<nombre>, que es donde una definición generada suele llevar su cambio rupturista.
Al comparar esquemas, las palabras clave required, enum, type, allOf, anyOf y oneOf se tratan como conjuntos, así que un documento regenerado que solo las reordena no se informa como cambio.
Las operaciones se emparejan por método y ruta. Por eso un parámetro de ruta renombrado aparece como una operación eliminada más una operación añadida, y no como una sola edición. Las referencias internas del propio documento (#/components/...) se resuelven antes de comparar; las referencias externas y remotas no se descargan, así que un parámetro o esquema que solo existe en otro archivo se compara tal como está escrito.
Los documentos Swagger 2.0 se comparan igual, porque rutas, operaciones, parámetros y respuestas se leen del mismo modo. No se comparan servers, requisitos de seguridad, etiquetas, descripciones ni ejemplos.
Cada entrada lleva su gravedad (DANGER, WARNING, INFO o GOOD), el JSON Pointer del elemento afectado y una frase que describe el cambio. En un pointer, ~1 representa una barra dentro de una ruta, de modo que /paths/~1users/get es GET /users.
Una casilla vacía se informa como tal, y un documento que no es JSON o YAML válido se rechaza indicando la línea que falló, así que un pegado roto nunca parece una comparación limpia.