openapi-diff: Compare Two OpenAPI Specs
openapi-diff compares two OpenAPI specs and classifies the differences as breaking (incompatible) or non-breaking.
openapi-diff (the OpenAPITools/openapi-diff Java tool) is an alternative to oasdiff for breaking-change detection, often chosen by JVM-centric teams already running OpenAPI Generator.
What it does
openapi-diff takes two spec paths or URLs (old then new), computes the differences, and marks incompatible changes. It can render the report as console text, Markdown, HTML, or JSON, and can fail the process on incompatible changes.
Common usage
openapi-diff old.yaml new.yaml
# fail CI when the change is backward-incompatible
openapi-diff --fail-on-incompatible old.yaml new.yaml
# emit a Markdown report for a PR comment
openapi-diff --markdown changes.md old.yaml new.yamlOptions
| Flag | What it does |
|---|---|
| --fail-on-incompatible | Exit 1 when incompatible changes are found |
| --fail-on-changed | Exit 1 when any change is found |
| --markdown <file> | Write a Markdown report |
| --html <file> | Write an HTML report |
| --json <file> | Write a JSON report |
| --info | Also compare the info section |
In CI
Compare the PR spec against the last released spec with --fail-on-incompatible as a required check, and attach --markdown output as a PR comment so reviewers see exactly what changed. As with any diff tool, feed it bundled single-file specs to avoid $ref resolution surprises.
Common errors in CI
Exit code 0 means no incompatible change, 1 means incompatible (with --fail-on-incompatible). Console output separates What's Changed, What's Deprecated, and breaking removals. "Unable to parse ..." or a Jackson JsonParseException means invalid YAML/JSON. A Could not find ... error means a bad file path or unreachable URL.