OpenAPI Diff

Optic computes a semantic diff of your OpenAPI specifications across Git branches, tags or commits. It has full support $ref and always loads the correct version of all the dependencies your OpenAPI resolves. The result of an OpenAPI diff is a list of API changes group by API endpoint:

optic diff openapi.yml --base main

 
✔ TodoAPI openapi.yml
Operations: 1 operation changed
 
✔ GET /users/me/todos:
   - response 200:
     - body application/json; charset=utf-8:
       - property /schema/properties/current_user_url: changed
       - property /schema/properties/current_user_authorizations_html_url: changed
       - property /schema/properties/authorizations_url: changed
 
...and 3 other operations

Here are a few other ways to call diff:

optic diff d100855:openapi.yaml 6ec96c:openapi.yaml

optic diff main:openapi.yaml feature/example:openapi.yaml

optic diff openapi.yaml --last-change

Using Checks

Optic helps you catch problems before your API changes get deployed by testing each set of changes. You can write checks that hook into your API's changes to detect breaking changes, problematic API designs, security issues and other problems.

Just start using the --check flag. You can configure our built-in checks here. By default, Optic will run breaking changes detection:

optic diff openapi.yml --base main --check

Severity + Validation

diff exits 1 when on your OpenAPI is invalid OR if it fails any of the checks. You can lose the OpenAPI validation (not recommended) if you want to try Optic and your current specification is invalid. You can also change the severity to info

• --validation (optional) - specify the level of validation on HEAD specs (choices: "strict", "loose", default: "strict")
• --severity (optional) - specify the severity level to exit with exit code. Use --severity "info" to exit 0 even when there are errors

Visualize changes

Large API diffs can be difficult to read. Visualize the effective API changelog if you pass the --web flag making it easy to understand the scope of your changes:

optic diff openapi.yml --base main --check --web

Setup in CI

Setting up Optic in CI will add a visual changelog to your Pull Requests, as well as run all your API standards, prevent breaking changes and ensures that every API specification is accurate.

Next: Set up Optic in CI