Diff OpenAPI
Developers need readable, accurate, API changelogs to review each other's proposed API changes. optic diff
outputs a semantic OpenAPI diff. Real changes to the API behavior will show up in the diff while refactors such as changing the order of parameters, adding new $ref
references, or reformatting the YAML will not show up as actual API changes. You can read the source code or read more about how it works here.
Compatibility
- Validates against the OpenAPI 3.1 or 3.0 specification.
- Every
$ref
reference to a URL must be valid YAML/JSON and resolvable from the machine runningoptic
- Circular references will not break the tool, but schemas including circular references will be truncated
Git Branches use case
This method of calling optic diff
compares the versions of the specification on HEAD:openapi.yaml
to main:openapi.yaml
. If your specification contains $ref
references to other files in the git repo, they will be loaded from the correct git tree.
optic diff openapi.yaml --base main

optic diff
works off the objects in your local copy. If you are seeing different results running locally than in CI, make sure you've fetched the latest commits.
If you add a new OpenAPI file (for instance for a new microservice), and it only exists in your HEAD branch, Optic will compare it to an empty OpenAPI file. Most of the time this has the expected behavior: everything will appear as added
in the changelog
Two files use case
This method of calling optic diff
compares two OpenAPI files directly. It is most often used by teams who use a different OpenAPI file for each version of their API. The first argument is from
and the second argument is to
optic diff v1.yaml v2-beta.yaml
Comparing arbitrary versions of your OpenAPI files
If you want to compare arbitrary versions of the files, you can use the rev:name
format (from git show
). This example compares the version of the spec on d100855
to the spec on 6ec96c
.
optic diff d100855:openapi.yaml 6ec96c:openapi.yaml
If you want to diff by tag, use git rev-parse [tag]
to look up the commit sha
optic diff $(git --oneline rev-parse v2.0.0):openapi.yaml $(git --oneline rev-parse v3.0.0):openapi.yaml