oasdiff — OpenAPI Breaking-Change Diff CLI

Practical Notes

• Use breaking as a hard gate; use changelog to help reviewers.
• CI tip: store previous spec as an artifact and compare on PR.

CI gate: block incompatible API changes

The common failure mode is “a schema field got renamed and nobody noticed”. Make it explicit by comparing base vs revision on every PR:

oasdiff breaking openapi.base.yaml openapi.pr.yaml

If breaking changes exist, the command exits non-zero, which is ideal for CI.

Reviewer UX: attach a human-friendly changelog

In addition to failing CI, provide a readable summary:

oasdiff changelog openapi.base.yaml openapi.pr.yaml > oasdiff.changelog.txt

Paste the key lines into the PR description (or post via a bot).

Practical tips

• Normalize specs first (same bundling/flattening strategy) to reduce false diffs.
• Keep specs in-repo so agents and CI can diff deterministically.
• If your spec comes from codegen, pin the generator version and compare the generated output.

FAQ

Q: Does it only detect breaking changes? A: No. It can also output full diffs and changelogs; breaking is the strict subset for gates.

Q: Can I compare URLs instead of files? A: Yes—oasdiff supports various inputs; keep CI inputs stable for deterministic results.

Q: How do I reduce noisy diffs? A: Ensure both specs are normalized the same way (flattening, ordering, bundling).