This is a quick tutorial that shows you how to catch breaking changes with Optic
1. Install the Optic CLI
2. Clone the demo repo
git clone https://github.com/opticdev/openapi-demo
3. Use the
diff command to compare the two versions of the OpenAPI specification.
optic diff todo-api.yaml todo-api-breaking-change.yaml
In this example there are two changes between the versions:
- We made
numberinstead of a
- We have renamed
- response 200:
- body application/json:
- field message added
- field name removed
- field status
- schema changed
Both of these changes are breaking. Let's see if Optic can catch them.
4. Now let's run the
diff with the
optic diff todo-api.yaml todo-api-breaking-change.yaml --check
FAIL GET /todos
Rule: prevent removing response property
x removed property name
removing a required response property is a breaking change
Rule: prevent response property type changes
x changed type of property status
changing the type of a response property is a breaking change
3 changes detected
1 checks passed
2 checks failed
Optic found two breaking changes:
- the first is from renaming
messageis not breaking, but removing
namecould break clients who were using that property.
- the second is changing
number. This will break clients that parse that property as a string.
If we include the
--web flag Optic will visualize the API diff and issues:
5. Try it yourself!
Run breaking change checks on your own OpenAPI files
- Create a branch
- Make a breaking change (e.g. removing a property, making an optional parameter required, removing an operation)
- Run breaking change checks between your current branch and the default branch
optic diff specs/service-api.yaml --base main --check
Using Optic as you write OpenAPI
Optic can help you understand if any of the changes you're proposing to the API are breaking. The tool is built to work alongside Git to make it easy to compare OpenAPI versions across branches.
optic diff openapi.yaml --base main --check
base is the branch you want to compare against, usually if you are working on feature branches it will be the name of your default branch.
Catch Breaking Changes in CI
You can set up Optic Cloud to catch breaking changes in CI. Optic can be set up to fail CI on Pull Requests that introduce known breaking changes to consumers. Get started here