OpenAPI Diff

Qué comprueba esta herramienta — y qué significa realmente «incompatible»

Un cambio es incompatible cuando un cliente escrito correctamente contra la especificación antigua puede fallar contra la nueva sin cambiar ni una línea de su propio código. Esa definición guía cada veredicto de esta página. Eliminar una ruta o una operación es incompatible porque las llamadas existentes no tienen adónde ir. Eliminar un estado de respuesta —sobre todo un 2xx— es incompatible porque el manejo de errores del cliente se escribió alrededor del conjunto antiguo. Añadir un parámetro obligatorio o una propiedad de petición obligatoria es incompatible porque la petición válida de ayer es rechazada de repente. Cambiar el tipo o el formato de un campo es incompatible porque los analizadores, validadores y SDK generados dependen del tipo declarado. Eliminar un valor de enumeración es incompatible porque un cliente puede seguir enviándolo, o guardar datos que ya no puede interpretar. Todo lo demás —un endpoint nuevo, un parámetro opcional, un campo de respuesta nuevo, un valor de enumeración nuevo, un código de estado nuevo— se informa como compatible: los clientes antiguos siguen funcionando, aunque aún no puedan usar la nueva capacidad.

La comparación es estructural, no textual. Ambos documentos se normalizan en el mismo modelo antes de comparar nada: cada ruta y operación, sus parámetros indexados por nombre y ubicación, su cuerpo de petición y cada respuesta reducidos a una firma de esquema: un resumen determinista de tipos, formatos, nombres de propiedades, listas de obligatorios y valores de enumeración, construido recursivamente y con las referencias locales $ref resueltas. Por eso reordenar claves, reformatear espacios o reescribir cada descripción produce una comparación vacía: nada de eso cambia el contrato. Y por eso un cambio enterrado a tres niveles dentro de un esquema referenciado también se encuentra: la firma expande la referencia en lugar de comparar su nombre.

Se aceptan dos formas de entrada porque el ecosistema publica ambas: primero se intenta JSON y, cuando eso falla, el texto se analiza como YAML, el formato que usan la mayoría de los documentos OpenAPI escritos a mano. Los documentos Swagger 2.0 también funcionan, incluidos sus parámetros in: body y los esquemas por respuesta. Deliberadamente no hay obtención remota ni subida: pega los documentos o suelta los archivos, igual que harías con una captura HAR, y la comparación se ejecuta cuando pulsas el botón —no con cada tecla—, de modo que dos especificaciones grandes pegadas siguen respondiendo con fluidez.

Usa el resultado como una puerta de publicación, no como decoración. En una revisión, la lista de incompatibles es el orden del día: cada entrada necesita una corrección, una subida de versión, una ventana de obsolescencia o una decisión escrita de que la ruptura es intencionada y está comunicada. La lista de compatibles es el borrador del registro de cambios. Exportar la comparación como JSON te permite archivar esa decisión junto a la versión, y el resumen copiable entra directamente en una solicitud de cambios: la misma disciplina que aplicarías a un cambio de contrato de webhook, donde una carga alterada en silencio rompe a todos los suscriptores a la vez.

Límites honestos, dichos con claridad. Esta herramienta compara el contrato declarado: no puede ver el comportamiento que la especificación no declara, como un campo que mantiene su tipo pero cambia su significado, una regla de negocio nueva, límites de velocidad más estrictos o un mensaje de error que los clientes analizaban (imprudentemente). Sigue las referencias locales y compara esquemas hasta una profundidad limitada, así que los esquemas patológicamente anidados o mutuamente recursivos se resumen en lugar de expandirse para siempre. Y una comparación con cero cambios incompatibles no es una promesa de que una actualización sea segura: es la evidencia de que el contrato documentado se mantuvo, que es exactamente la evidencia que vale la pena tener antes de desplegar.