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

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