OpenAPI diff for breaking changes

What it does

Compares an old and a new API spec (OpenAPI 3.0, 3.1 or Swagger 2.0) and classifies each change as breaking, needs review or non-breaking.

• Removed paths and methods (renaming {petId} to {id} is not treated as a removal)
• New required parameters, optional to required, request body becoming required, media types no longer accepted
• Response fields removed, no longer required or now nullable, removed success responses
• Type changes with direction awareness (request vs response, integer to number widening), enum values removed or added, tightened constraints such as maxLength
• Handles $ref, allOf merging, recursive schemas, readOnly and writeOnly
• Authentication newly required, server URL changes

How to use

python scripts/openapi_diff.py old.yaml new.yaml --markdown api-diff.md

The agent reviews the result for renames and real client impact, then recommends the version bump, a deprecation path and changelog entries. Exit code is 1 when breaking changes exist, so it also works in CI.

Requirements

• Python 3 (standard library only)
• YAML is read with PyYAML when installed, otherwise with a built-in reader for the common subset. For YAML with anchors, aliases or tags, install PyYAML or convert the spec to JSON.

Caveats

• It compares specs only; behaviour changes not visible in the spec (defaults, error formats) are not detected.
• External $ref files are not followed; bundle split specs into one file first.