OpenAPI Diff

What the OpenAPI diff detects

The browser engine compares HTTP operations by method and path. Removing an operation is breaking; adding one is non-breaking. For operations that exist in both versions, it reports added required parameters, added optional parameters, removed parameters, and a request body that became required. It also inspects the first direct 2xx response schema and reports removed properties, added properties, changed primitive types, and properties that are no longer guaranteed.

Breaking-change example

If GET /v1/users/{id} previously returned required properties id and email, removing email is classified as breaking because generated clients or application code may read it. Adding a new optional response property is non-breaking. Adding a required query parameter is breaking because existing callers do not send it.

Use the deployed contract as the baseline

For pull requests, compare the candidate document with the exact artifact from the base revision, not a mutable URL downloaded at an arbitrary time. Validate both documents before interpreting the result. A malformed or partially generated spec is not a reliable compatibility baseline. Keep the diff engine version and policy stable in CI so the same input produces the same decision locally and in automation.

Scope and limitations

This free tool intentionally uses a focused, transparent ruleset. It does not resolve external $ref documents, execute custom linter rules, align renamed schemas, or prove that a running server matches the specification. Direct response schemas are inspected; referenced component changes require a deeper resolver. A missing result therefore means “no supported structural change detected,” not “every possible client remains compatible.”

YAML support covers ordinary mappings, lists, and scalar values used by many compact specs. Anchors, aliases, flow-style collections, and multi-document YAML are outside the current parser. Convert advanced YAML to JSON first when exact parsing matters.

From one-off diff to continuous monitoring

A manual diff is useful during review. Production APIs also change outside planned pull requests through generated artifacts, gateway configuration, or another repository. Cryonel API Guard stores a normalized monitored specification, checks it on a schedule, preserves change history, and turns detected changes into alerts. Start with this local tool to understand the rules, then monitor the contract when drift becomes an operational risk.