We will get to the sexy part in a moment, but in a nutshell openapi-changes allows you to see and explore what has changed with your OpenAPI Specification, between a single change, or for all time!

Explore OpenAPI change history using a terminal or a browser, you decide which experience suits you. Perfect for individual use, or in a CI/CD pipeline for automation.

This is an early tool and is active, daily development

Have you ever seen an OpenAPI diff report look like this?

What about a terminal UI that does the same?

See all the documentation at https://pb33f.io/openapi-changes/

• Installing openapi-changes
• Configuring breaking changes
• Command arguments
• CLI Commands
  • console command
  • html-report command
  • report command
  • summary command
• About openapi-changes

Are you ready to try it out?

brew install pb33f/taps/openapi-changes

npm i -g @pb33f/openapi-changes

If you prefer yarn (recommended)

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 architectures.

To run, mount the current working dir to the container like so:

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

The console cannot run via docker.

Supported in v0.91+

openapi-changes uses libopenapi's configurable breaking change detection system. You can customize which changes are considered "breaking" by providing a configuration file.

# Use explicit config file
openapi-changes summary -c my-rules.yaml old.yaml new.yaml

# Or place changes-rules.yaml in current directory (auto-detected)
openapi-changes summary old.yaml new.yaml

openapi-changes searches for changes-rules.yaml in:

1. Current working directory (./changes-rules.yaml)
2. User config directory (~/.config/changes-rules.yaml)

Create a changes-rules.yaml file:

# Custom breaking rules configuration
# Only specify overrides - unspecified rules use defaults

# Make operation removal non-breaking (for deprecation workflows)
pathItem:
  get:
    removed: false
  post:
    removed: false
  put:
    removed: false
  delete:
    removed: false

# Make enum value removal non-breaking
schema:
  enum:
    removed: false

# Make parameter changes non-breaking
parameter:
  required:
    modified: false

Each rule has three options:

• added: Is adding this property a breaking change? (true/false)
• modified: Is modifying this property a breaking change? (true/false)
• removed: Is removing this property a breaking change? (true/false)

You can configure rules for these OpenAPI components:

For the complete list of configurable properties and more examples, see the full configuration documentation.

Check out all the docs at https://pb33f.io/openapi-changes/