Optic has built in linting support for OpenAPI and is compatible with your existing Spectral rules. Optic can lint both
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
Optic also supports interopability with your existing Spectral rules! 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! 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
--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