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

Diffing multiple specifications

If your team has multiple OpenAPI specifications in the same repository, you can diff all of them with diff-all:

optic diff-all --compare-from main --match "/apis/**/openapi.yml" --check

• --match (optional) - use a glob to match specific file name patterns
• --ignore (optional) - use a glob to disqualify specific file name patterns. If a file matches this pattern and the match pattern it will be ignored.

Severity + Validation

Both diff and diff-all exit 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

If you like the visual changelogs, you can add them to your Pull Request and Merge Requests