CLI Configuration Reference

This is a complete reference for the Optic CLI configuration (optic.yml) file. Templating via Handlebars is supported. See the docs for details.

Each block below represents a top-level section within the optic.yml file.

external_refs

Configure how Optic resolves external $refs in OpenAPI specs. Useful for authenticating refs in private repos.

# optic.yml
external_refs:
  resolve_headers:
    # Add headers to `$ref`s matching the URL prefix.
    - url_prefix: 'https://gitlab.com'
      headers:
        Authorization: 'Bearer {{TOKEN}}'

View the documentation.

capture

Configure the optic capture command.

# optic.yml
capture:
  openapi.yml:
    server:
      # The command to run your server.
      # (Optional) If omitted, Optic assumes the server is running or started elsewhere.
      command: your-server-command
 
      # The url where your server can be reached once running.
      # (Required) Can be overridden with '--server-override'.
      url: http://localhost:8080
 
      # A readiness endpoint for Optic to validate before sending requests.
      # Optional: If omitted, perform no readiness checking.
      ready_endpoint: /
 
      # The interval to check 'ready_endpoint', in ms.
      # (Optional) default: 1000
      ready_interval: 1000
 
      # The length of time in ms to wait for a successful ready check to occur.
      # (Optional) default: 10_000, 10 seconds
      ready_timeout: 10_000
 
    # One of 'requests.run' or 'requests.send' is required. Both is OK.
    # Run an external command to generate traffic.
    requests:
      run:
        # The command to run to generate traffic (e.g., your test command, etc.).
        command: your-test-command
 
        # The name of the environment variable injected into the env of 'command' that contains the address of the Optic proxy.
        # (Optional) default: OPTIC_PROXY
        proxy_variable: OPTIC_PROXY
 
      # Use Optic to generate requests.
      send:
        - path: /users/create                            # (Required)
          method: POST                                   # (Optional): default: GET
          headers:                                       # (Optional)
            content-type: application/json;charset=UTF-8 # (Optional): If omitted, `content-type` is added with this default
          data:                                          # (Optional): If omitted on a POST request, default: {}
            name: Hank
 
    config:
      # The number of parallel requests to make when using 'requests.send'.
      # (Optional) default: 4
      request_concurrency: 4

View the documentation.

ruleset

Configure rules and styles for optic diff|run.

# 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:
      # Remote URLs and local paths are supported.
      always:
        - https://www.apistyleguides.dev/api/url-style-guides/3ba0b4a
      added:
        - ./spectral.yml

View the documentation.