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 json and 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

Using Spectral

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 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!
      added:
        - https://www.apistyleguides.dev/api/url-style-guides/3ba0b4a

Diffing your files

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

What's next?

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