Forwards only checks
Linters are a great way to standardize your endpoints, but most of the time you already have existing endpoints that don't match your lint rules. Optic's rule runner is built to support only running rules on newly added endpoints, requests and responses.
Optic can run checks on both
yaml OpenAPI files and is compatible with your existing spectral rules.
Configuring your rules
Get started by creating an
optic.yml file at the root of your repository, and copying in the following rulesets:
ruleset: # Enforce naming conventions in your API - naming: required_on: added 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: added 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
Notice that we've set
added - this means that these rules will only run on newly added endpoints or fields!
Optic also supports interopability with your existing Spectral rules, where you can configure your Spectral rules to only run on newly added endpoints, requests and responses! To do this, you'll need to ensure you have the
npm install -g @stoplight/spectral-cli
Once you've installed the
spectral-cli, modify your
optic.yml file with spectral config.
ruleset: ... - spectral: # You can also point this at your own `spectral.yaml` file! added: - https://www.apistyleguides.dev/api/url-style-guides/3ba0b4a
This will run your existing spectral rules, but only trigger when a new endpoint or field is added!
Diffing your files
Since we're only running rules against newly added endpoints, we need to have two versions of a spec to compare
Once you've set up your rules, it's as simple as running
optic diff my-spec.yml --base HEAD~1 --check # Or alternatively, if you are on a different git branch optic diff my-spec.yml --base main --check # Or even diff two different files! optic diff my-spec-v1.yml my-spec-v2.yml --check
--web to the end of this command to open up a detailed web view of the diff and changes!
Forwards only governance isn't the only thing Optic can do! Take a look at some of our other guides:
- Configure Optic to run breaking changes detection
- Set up Optic in CI (GitHub or GitLab) to enforce your linting rules