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.
Optic will look for a .optic.env
in the following locations:
- The directory where the
optic.yml
file is located. - The current directory.
- The root of the Git repository.
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.