openapi-changes lets you inspect what changed in an OpenAPI or AsyncAPI 3.x specification between two files, between git revisions of the same file, across local git history, or directly from a GitHub-hosted file URL.

It can render the same semantic change model as:

• an interactive terminal UI
• a terminal summary
• a machine-readable JSON report
• a markdown report
• a self-contained offline HTML report

It works well for local exploration, CI/CD checks, release notes, and API review workflows.

Event-driven APIs break too. They just do it quietly, in a consumer nobody remembers subscribing to that topic.

openapi-changes now speaks AsyncAPI 3.x natively. Same commands, same reports, same time machine.

openapi-changes summary previous-asyncapi.yaml asyncapi.yaml
openapi-changes report HEAD~1:asyncapi.yaml HEAD:asyncapi.yaml
openapi-changes html-report --report-file changes.html previous-asyncapi.yaml asyncapi.yaml

The format is detected from the document, including across git history and revision-scoped references. Both sides of a comparison must use the same format, and AsyncAPI 2.x is not supported.

Existing rule files keep their OpenAPI meaning. To configure both engines, use named sections:

openapiRules:
  info:
    description:
      modified: false
asyncapiRules:
  channel:
    address:
      modified: false
schemaRules:
  schema:
    type:
      modified: false

Read the AsyncAPI docs >

openapi-changes gives you the power to view all changes between two OpenAPI contracts, and over time in every which way you can possibly think of. Graphs, trees, lists, diffs, JSON, mark down.

Has no network dependencies at all. Runs 100% offline, including the HTML report.

brew install pb33f/taps/openapi-changes

npm i -g @pb33f/openapi-changes

If you prefer yarn:

yarn global add @pb33f/openapi-changes

curl -fsSL https://pb33f.io/openapi-changes/install.sh | sh

docker pull pb33f/openapi-changes

Docker images are available for both linux/amd64 and linux/arm64.

The published image configures Git to trust mounted repositories, so local git-history commands work without requiring extra safe.directory setup inside the container.

To run a command, mount the current working directory into the container:

docker run --rm -v $PWD:/work:rw pb33f/openapi-changes summary . sample-specs/petstorev3.json

To run the interactive console through Docker, allocate a TTY with -it:

docker run --rm -it -v $PWD:/work:rw pb33f/openapi-changes console . path/to/openapi.yaml

Print the installed version:

openapi-changes version

Comes in multiple themes! PB33F (Dark), Roger Mode (Light) and Tektronix (Retro Dark)

A self-contained, offline HTML report with interactive timeline, change explorer graph, diff views, and more.

Compare a file at different git revisions without checking out branches:

openapi-changes summary HEAD~1:openapi.yaml ./openapi.yaml
openapi-changes html-report main:api/openapi.yaml feature-branch:api/openapi.yaml

The revision:path syntax works with any git ref -- branches, tags, HEAD~N, commit SHAs. The path is relative to the repository root. This works with all commands and supports multi-file specs with $ref references resolved from the same revision.

Full docs: https://pb33f.io/openapi-changes/

• Installing openapi-changes
• Comparing AsyncAPI specifications
• Configuring breaking changes
• Command arguments
• Commands:
  • console
  • summary
  • report
  • markdown-report
  • html-report
  • completion
  • version
• About openapi-changes

openapi-changes currently requires Go 1.26.10+. The npm installer requires Node.js 20+.

The report UI uses Node.js 24.15+ in the Node 24 release line. Run npm ci, npm run typecheck, npm test, and npm run build in html-report/ui after dependency changes. Commit the full and lite bundles in build/static so go install embeds the same patched code. Mermaid stays on the supported 11.x line; its KaTeX override supplies the patched trust checks.

Use the pb33f-maintained go-yaml, testify, and jsonschema/v6 modules. Validate Go dependency updates with GOWORK=off to avoid local workspace replacements.

Terminal Markdown reports wrap long table content and use clickable links in terminals that support OSC 8 hyperlinks.

git clone https://github.com/pb33f/openapi-changes.git
cd openapi-changes
go build -o bin/openapi-changes .

Or use make:

make

The current command surface is:

• console for the interactive terminal UI
• summary for fast terminal and CI output
• report for machine-readable JSON
• markdown-report for shareable markdown output
• html-report for the interactive offline browser report
• completion for shell completion scripts
• version for raw build version output

Run openapi-changes --help or openapi-changes <command> --help for the live CLI surface.

The terminal-facing commands support multiple presentation modes:

• --no-color for the light Roger monochrome theme
• --roger-mode as an alias for --no-color
• --tektronix for the green monochrome terminal theme

See the command arguments docs for the full shared flag set.

openapi-changes supports configurable breaking-change rules via changes-rules.yaml.

openapi-changes summary -c my-rules.yaml old.yaml new.yaml

openapi-changes summary old.yaml new.yaml

Default lookup locations:

1. ./changes-rules.yaml
2. ~/.config/changes-rules.yaml

pathItem:
  get:
    removed: false
  post:
    removed: false
  put:
    removed: false
  delete:
    removed: false

schema:
  enum:
    removed: false

parameter:
  required:
    modified: false

Each rule supports:

• added
• modified
• removed

For the full rules reference and more examples, see the configuration docs.

See the full docs at https://pb33f.io/openapi-changes/

Use the lightweight GitHub Action for a compact job summary, full report artifacts, and a breaking-change check.