!logo


OpenAPI Changes

The world's _sexiest_ OpenAPI diff tool.

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

How is it the 'sexiest'?

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


What about a terminal UI that does the same?


---

Documentation

$3

$3

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?

Install using homebrew tap

``bash
brew install pb33f/taps/openapi-changes
`

---

Install using npm or yarn

`bash
npm i -g @pb33f/openapi-changes
`

If you prefer yarn _(recommended)_

`bash
yarn global add @pb33f/openapi-changes
`

---

Install using cURL

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

Install/run using Docker

`bash
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.

---

Custom Breaking Rules Configuration

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

$3

`bash


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
`

$3

openapi-changes searches for changes-rules.yaml in:
1. Current working directory (./changes-rules.yaml)
2. User config directory (~/.config/changes-rules.yaml)

$3

Create a changes-rules.yaml file:

`yaml


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
`

$3

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)

$3

You can configure rules for these OpenAPI components:

| Component | Description |
|-----------------------|----------------------------------------------------|
| paths | Path definitions |
| pathItem | Operations (get, post, put, delete, etc.) |
| operation | Operation details (operationId, requestBody, etc.) |
| parameter | Parameter properties (name, required, schema) |
| schema | Schema properties (type, format, enum, properties) |
| response | Response definitions |
| securityScheme | Security scheme properties |
| securityRequirement` | Security requirements |

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/