Setting an API Style Guide
Optic checks that every change you make to an API matches your team's style guide. To get started, create an optic.yml
file in the root of your repository. The rulesets you enable in this file will be when you run Optic on an OpenAPI specification in a child directory.
optic.yml
ruleset:
# Prevent breaking changes
- "breaking-changes"
# Enforce naming conventions in your API
- naming:
required_on: always
requestHeaders: Capital-Param-Case
responseHeaders: param-case
properties: Capital-Param-Case
pathComponents: param-case
queryParameters: snake_case
# Require your OpenAPI has examples, and that those examples match the schema
- examples:
required_on: always
require_request_examples: true
require_response_examples: true
require_parameter_examples: true
# (optional) allow certain operations do not need examples
exclude_operations_with_extension: x-legacy-api
- documentation:
required_on: always
require_property_descriptions: true
require_operation_summary: true
require_operation_description: true
require_operation_id: true
# (optional) allow certain operations do not need examples
exclude_operations_with_extension: x-legacy-api
- spectral:
# You can also point this at your own `spectral.yaml` file!
always:
- https://www.apistyleguides.dev/api/url-style-guides/3ba0b4a
added:
- ./spectral.yml
optic diff openapi.yml --check
Built-in Rulesets
The community maintains a few of the most common rulsets for governing APIs. They are a great start and can easily be extended with customer rules as needed.
Custom Rules
Optic's Rule DSL lets you write rules about API changes. Here is an example rule:
response.property.changed((before, after) => {
if (before.required && !after.required)
throw new Error("Making a response property optional is a breaking change")
})
Learn about adding your own custom rules here.
Run in CI
Setting up optic run
in your CI pipeline ensures that every API specification is accurate, follows your standards, and contains no breaking changes.