Documentation
Compare OpenAPI Files

Prevent breaking changes

Optic can compute the changes between any two specs. This makes it easy to catch breaking changes in development and CI, long before they make it to production and break a consumer.

The diff command integrates with Git to make comparisons easy:

optic diff openapi.yml --base main --check
  • --base is the base branch or sha you want to compare your working copy to
  • --check tells Optic to run checks - you can configure these checks by adding an optic.yml file. By default, Optic will run breaking changes detection.
ℹ️

If you already have an optic.yml file, add the breaking-changes ruleset to it

optic.yml
ruleset:
  - breaking-changes

Visualize changes

Optic can 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
💡

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 specs: If you add a new OpenAPI spec (for instance for a new microservice), and it only exists in your HEAD branch, Optic will compare it to an empty OpenAPI spec. Most of the time this has the expected behavior: everything in the spec will be marked as added.

Comparing arbitrary versions of your OpenAPI specs

If you want to compare arbitrary versions of the specs, 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

Add Optic to CI

Great! You've now added your documentation to Optic Cloud, the next step is to set this up in CI so that Optic checks for breaking changes on every API change, making sure you never make an unintentional breaking change again. Follow our guide for GitHub or GitLab. Setting Optic up in CI also gets you:

  • Beautiful documentation with history
  • Automatic breaking change detection and consistent naming conventions standards
  • API statistics such as changes over time and breaking changes introduced in the last 6 months
Forwards Only ChecksConfigure API Standards