Docs
API Style Guides

Setting an API Style Guide

Optic checks that every change you make to an API matches your team's style guide. To get started, create an optic.yml file in the root of your repository. The rulesets you enable in this file will be when you run Optic on an OpenAPI specification in a child directory.

optic.yml
ruleset:
  # Prevent breaking changes
  - "breaking-changes"
  # 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
  - documentation:
      required_on: always
      require_property_descriptions: true
      require_operation_summary: true
      require_operation_description: true
      require_operation_id: true
      # (optional) allow certain operations do not need examples
      exclude_operations_with_extension: x-legacy-api
  - spectral:
      # You can also point this at your own `spectral.yaml` file!
      always:
        - https://www.apistyleguides.dev/api/url-style-guides/3ba0b4a
      added:
        - ./spectral.yml
optic diff openapi.yml --check

alt

Built-in Rulesets

The community maintains a few of the most common rulsets for governing APIs. They are a great start and can easily be extended with customer rules as needed.

Custom Rules

Optic's Rule DSL lets you write rules about API changes. Here is an example rule:

response.property.changed((before, after) => {
  if (before.required && !after.required)
      throw new Error("Making a response property optional is a breaking change")
})

Learn about adding your own custom rules here.


Run in CI

Setting up optic run in your CI pipeline ensures that every API specification is accurate, follows your standards, and contains no breaking changes.

Next: Set up Optic in CI