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 anoptic.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
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