Get started with openapi-changes

Value in 30 seconds, or your money back.

If you want the fastest path from install to useful output, this page is it.

1. Install openapi-changes

brew install pb33f/taps/openapi-changes

If you do not use Homebrew, see the other installation options.

2. Generate an HTML report

Use the OpenAPI Petstore fixture hosted on GitHub to generate the interactive report:

openapi-changes html-report https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore.yaml

This writes report.html into your working directory.

3. Open the report

open report.html

4. Explore the same data in the console

openapi-changes console https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore.yaml

5. Print a terminal summary

openapi-changes summary https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore.yaml

6. Export structured reports

openapi-changes report https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore.yaml | jq

openapi-changes markdown-report https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore.yaml

7. Compare git revisions

If your spec lives in a git repository, compare it across revisions without checking out branches:

openapi-changes summary HEAD~1:openapi.yaml ./openapi.yaml

The revision:path syntax works with branches, tags, HEAD~N, and commit SHAs. Multi-file specs with $ref references are resolved from the same revision.

8. Try a different fixture

The repo also ships with its own jazzy petstore sample:

openapi-changes console https://github.com/pb33f/openapi-changes/blob/main/sample-specs/petstorev3.json

9. Compare AsyncAPI specifications

Every command also works with AsyncAPI 3.x documents:

openapi-changes summary previous-asyncapi.yaml asyncapi.yaml