Prevent Breaking Changes
Most breaking changes are released by accident. It can be difficult for developers to understand which of their API changes are breaking and which are backwards-compatible. Optic tests for breaking changes locally and in CI pipelines, so you catch them before they hit production.
Basic:
Just add the breaking-changes ruleset to your optic.yml configuration.
ruleset:
# Prevent breaking changes
- breaking-changesMany teams have some endpoints they want to be exempted from the breaking change checks. When you set exclude_operations_with_extension developers will be allowed to break API endpoints that's have a specific extension ie x-beta or x-wip or x-draft:
Advanced Setup:
ruleset:
# Prevent breaking changes
- breaking-changes:
# Pick an extension for your work-in-progress operations.
# Breaking changes will be allowed here
exclude_operations_with_extension: x-draftRunning a optic diff
The diff command computes the semantic diff between two versions of your API. If you the breaking-changes ruleset configured, breaking changes will make the diff command to exit 1:
optic diff openapi.yml --base $HEAD_BRANCH --check
Running in CI
Running Optic in CI ensures breaking changes do not make it to production.
Next steps: Setup Optic CI
What does Optic consider a breaking change?
The community supported breaking-change ruleset checks for these breaking changes. If you want to define more breaking changes that make sense for your API check out custom rules.
Request Parameters
- Prevent adding a required Query Parameter
only applies to existing operations, new operations can have required query parameters
- Prevent changing an optional Query Parameter to required
only applies to existing operations, new operations can have required query parameters
- Prevent adding a required Header Parameter
only applies to existing operations, new operations can have required query parameters
- Prevent changing an optional Header Parameter to required
only applies to existing operations, new operations can have required header parameters
- Prevent adding a required Cookie Parameter
only applies to existing operations, new operations can have required query parameters
- Prevent changing an optional Cookie Parameter to required
only applies to existing operations, new operations can have required cookie parameters
- Prevent restricting the options for an enum Parameter
applies to parameters with enum schemas. Removing an option that was supported previously is a breaking change
- Prevent changing the type of Parameter
applies to parameters with schemas. Incompatible type changes are a breaking change
Operations
- Prevent removing an Operation
applies to every operation
- Prevent removing a documented Response Status Code
applies to every operation
Request Body Properties
- Prevent making an optional Property required
applies to existing properties in existing operations. Request Properties in new operations can be made required
- Prevent adding a required Property
applies to existing operations. Adding required properties is a breaking change. Request Properties in new operations can be made required
- Prevent changing the type of Property
Incompatible type changes are a breaking change
Response Body Properties
- Prevent making a required Property optional
applies to existing properties in existing operations. Response Properties in new operations can be made optional
- Prevent removing a required Property
applies to existing operations. Removing required response properties is a breaking change.
- Prevent changing the type of Property
Incompatible type changes are a breaking change