Comparador de Contratos de API

Pegas (o subes) una spec OpenAPI 3.x base (antigua) y una de revisión (nueva), y la herramienta recorre cada ruta, parámetro, cuerpo de petición, respuesta, requisito de seguridad y esquema de ambas, y luego informa qué cambió: endpoints añadidos o eliminados, cambios en requisitos de parámetros y campos de petición, tipos o enums restringidos, campos de respuesta o códigos de estado que desaparecieron, cambios en requisitos de seguridad y cambios de composición allOf/oneOf/anyOf.

Cualquier cosa que pueda hacer que un cliente existente deje de funcionar: un endpoint eliminado, un parámetro o campo de petición que pasó a ser obligatorio, un campo de respuesta o código de estado eliminado, un campo que ya no está garantizado en una respuesta, o un tipo/enum que se volvió más restrictivo (incluyendo los arrays de tipo nullable de OpenAPI 3.1, por ejemplo quitar "null" de `["string", "null"]`). Los endpoints nuevos, los campos opcionales nuevos y los campos de respuesta nuevos son aditivos y se muestran aparte como seguros.

Sí. Los requisitos de seguridad añadidos o eliminados (globales y por operación), los cambios en la definición del esquema de seguridad (por ejemplo, una clave de API que pasa de una cabecera a un parámetro de consulta), las operaciones recién marcadas como obsoletas y los cambios en la URL del servidor se informan todos - como hallazgos informativos en lugar de incompatibles o seguros, ya que (siguiendo la severidad por defecto que el propio oasdiff asigna a estas comprobaciones) ninguna dirección es universalmente correcta o incorrecta; tú decides si importa para tu API.

Sí. Los miembros de `allOf` se resuelven y combinan antes de comparar, así que un campo obligatorio añadido en lo profundo de un esquema compuesto sigue siendo detectado. Los conjuntos de variantes `oneOf`/`anyOf` se comparan y se marcan como informativos cuando se añade o elimina una variante, ya que si ese cambio concreto es incompatible depende de cómo tus clientes distingan entre variantes.

No - esto solo compara specs OpenAPI 3.x. Swagger 2.0 (el formato más antiguo) estructura parámetros y cuerpos de forma distinta, así que aplicar las mismas reglas daría resultados erróneos. Pegar un documento Swagger 2.0 produce un error claro en lugar de un diff silenciosamente incorrecto.

No. Tanto el análisis como la comparación se ejecutan en tu navegador - tu spec nunca sale de tu dispositivo, a diferencia de la mayoría de las otras herramientas de diff de OpenAPI, que procesan lo subido en su propio servidor aunque digan que no lo almacenan. Esto también es válido cuando usas la opción de subir archivo/arrastrar y soltar: el archivo se lee localmente y nunca se transmite.

Compara los cuerpos de petición y respuesta `application/json`, que cubre la gran mayoría de las API REST, pero no evalúa otros tipos de contenido, cabeceras de respuesta, descripciones ni ejemplos. Un `$ref` que apunta fuera del documento (un archivo o URL aparte) se informa como no resoluble en lugar de omitirse silenciosamente.

Sí, ambas cosas. Cada cuadro acepta JSON o YAML de forma independiente y detecta cuál usaste, así que puedes comparar una spec base en JSON contra una de revisión en YAML o viceversa. También puedes arrastrar un archivo .json/.yaml/.yml sobre cualquiera de los cuadros, o usar su botón Upload file - el archivo se lee en tu navegador y nunca se sube a ningún sitio.

Funciona con cualquier documento que tenga un campo "openapi": "3.x" y un objeto "paths", lo que cubre tanto 3.0 como 3.1 - incluyendo el `type` en forma de array de 3.1 (por ejemplo `["string", "null"]`) - y solo rechaza documentos que parezcan Swagger 2.0.

Se admiten Text (.txt), Markdown (.md) y JSON (.json) - elige uno en el desplegable de formato junto a Download report antes de descargar. La exportación JSON incluye la lista completa de hallazgos más los recuentos por severidad, así que se puede pasar a otro script (por ejemplo, una comprobación de CI) si lo necesitas.

Funcionan ambas cosas: pulsa Compare para una nueva ejecución instantánea, o simplemente sigue escribiendo - tras una breve pausa vuelve a comparar automáticamente. También puedes pulsar Ctrl+Enter (Cmd+Enter en Mac) desde cualquiera de los cuadros para comparar de inmediato sin esperar.