OpenAPI Diff y detector de cambios incompatibles

OpenAPI Diff compara una especificación de API base y una candidata por su significado, no por su texto. Empareja las operaciones por método y ruta (así, /users/{id} y /users/{userId} son el mismo punto de conexión), resuelve las referencias internas $ref e informa de cada cambio del contrato con su operación, ubicación, valores anterior y posterior, y por qué importa a los clientes. Admite Swagger 2.0, OpenAPI 3.0 y OpenAPI 3.1 en JSON o YAML, y Swagger 2.0 se normaliza primero a la estructura de OpenAPI 3.

1. 1.Pega, sube o importa la especificación base (la versión que usan hoy los clientes).
2. 2.Añade la especificación candidata (la versión propuesta).
3. 3.Pulsa Comparar.
4. 4.Revisa las pestañas Incompatibles, Advertencias y Retrocompatibles, y filtra por método o área.
5. 5.Selecciona un cambio para ver los valores anterior y posterior y por qué importa.
6. 6.Copia los cambios incompatibles para un pull request, o descarga el informe Markdown o JSON para CI.

Las solicitudes y las respuestas se evalúan en direcciones opuestas. Del lado de la solicitud (lo que envían los clientes), todo lo que restringe lo que se acepta es incompatible: un parámetro o propiedad obligatorios nuevos, un valor de enum eliminado, un tipo o formato modificado, un máximo menor o un mínimo mayor, un patrón nuevo o un tipo de contenido eliminado. Del lado de la respuesta (lo que reciben los clientes), todo lo que elimina o amplía lo que los clientes leen es incompatible o una advertencia: una propiedad o un estado de éxito eliminado, un tipo modificado, un valor de enum nuevo o una propiedad obligatoria que pasó a ser opcional. Los puntos de conexión eliminados, la autenticación nueva, los esquemas de seguridad modificados y los scopes de OAuth añadidos son incompatibles. Las ediciones de descripción, resumen, título y ejemplos son cambios de documentación y están ocultas salvo que las actives.

La comparación se ejecuta en tu navegador con un motor de reglas integrado; las especificaciones nunca se suben. La importación por URL obtiene el archivo directamente desde tu navegador sin cookies, así que los servidores que bloquean las solicitudes entre orígenes requieren subir o pegar el archivo. Cada especificación puede pesar hasta 5 MB. Los archivos $ref externos se notifican, pero no se obtienen. Los servidores, callbacks, webhooks, enlaces y extensiones de proveedor no se comparan, y las reglas describen el impacto probable en los clientes sin garantizarlo: un servidor estricto o permisivo puede comportarse de otra forma.