Skip to main content

Diff OpenAPI

Developers need readable, accurate, API changelogs to review each other's proposed API changes. The more clear the changes are, the easier it is design the API, share ideas, and ultimately ship a higher-quality API.

optic diff is a semantic OpenAPI diff. Real changes to the API behavior will show up in the diff. Refactors like 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. If you think our validation logic is too strict open an issue
  • Every $ref referenced file is valid YAML/JSON
  • Every $ref reference to a URL must be valid YAML/JSON and resolvable from the machine running optic
  • Circular references will not break the tool, but schemas including circular references will return empty schemas after one cycle.

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
Note on history

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.

Note on new OpenAPI files

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
Diff using tags

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

Next up: Testing for breaking changes and enforcing your API standards