Lint OpenAPI
Optic has built in linting support for OpenAPI and is compatible with your existing Spectral rules. Optic can lint both json
and yaml
OpenAPI files and is configurable to match your API.
Configuring your lint 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: 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
Using Spectral
Optic also supports interopability with your existing Spectral rules! To do this, you'll need to ensure you have the spectral-cli
installed:
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!
always:
- https://www.apistyleguides.dev/api/url-style-guides/3ba0b4a
This will now run your spectral rules along side your Optic rules!
Linting your files
Once you've set up your rules, it's as simple as running
optic lint my-spec.yml
Add --web
to the end of this command to open up a detailed web view of the lint results!
Forwards only linting
A lot of the time when rolling our new standards or lint rules, you will have existing API endpoints that does not conform to your lint rules. This is problematic because to add in new rules, you'll either have a lot of warnings or will need to rewrite all your existing API endpoints. Rewriting your existing API endpoints to match your standards usually means you'll be introducing breaking changes in the process.
Optic solves this by letting you apply different rulesets to added endpoints and legacy endpoints that are harder to change! Continue to our guide about forwards only governance