Advanced Configuration Reference

This document describes advanced configuration options you can take advantage of in your optic.yml file.

Templating optic.yml

The optic.yml file that is used to configure Rules, Capture, and other Optic features supports the Handlebars (opens in a new tab) template language. This is useful for keeping secrets out of your optic.yml file, or for generating dynamic configuration based on the environment.

For example, consider this configuration snippet where a request needs an Authorization header:

capture:
  openapi.yml:
    ...
    requests:
      send:
        - path: admin/users
          headers:
            authorization: bearer {{TOKEN}}

Running TOKEN=my-token optic config show will display the rendered template, with "my-token" substituted in the authorization header.

Setting Values

Values for the template are loaded from the environment. You can set them in a .optic.env file (where they are loaded by dotenv (opens in a new tab)), or set them in your environment using whatever method you choose.

Values set in .optic.env are overridden when set by other means in the environment (via export TOKEN=my-token, in a CI workflow, etc.).

Loading private $refs in an OpenAPI specification

If your OpenAPI specification uses $ref (opens in a new tab) to load additional specs from locations that require authorization you can configure Optic to add specific headers when resolving a matching $ref.

external_refs:
  resolve_headers:
    - url_prefix: 'https://gitlab.com'
      headers:
        Authorization: 'Bearer {{TOKEN}}'

This configuration will add an Authorization when fetching a $ref matching the prefix https://gitlab.com. The value for TOKEN is retrieved from the environment—See the preceding section for information about how the template system works.

REST API authentication links for common Git hosts

Consult your Git host's documentation for the correct tokens and headers to set when using a ref from a private repository.

• GitHub (opens in a new tab)
• GitLab (opens in a new tab)