Advanced Configurations in Optic
Optic setup
api init and the setup process should get you started. The following topics cover advanced configuration to tweak your setup and take advantage of more features in Optic. If you run into difficulties during install, please reach out to us with an issue so we can help you get situated. You don't have to resolve setup issues on your own!
Optic Command Wrapper task mode#
When you first setup Optic, a start task is added to your optic.yml file:
The task start in the above example is run using:
If your framework expects to take a parameter to define its port when starting, Optic provides the PORT environment variable to your process. You can pass that in the command parameter. If the PORT environment variable is already being used for some other reason in your environment and it causes conflicts with Optic's port assignment, you can use the alternative OPTIC_API_PORT if necessary:
You may also want a quick way to run your API tests, a Postman collection, etc. through Optic. To make this simple, Optic lets you define as many custom tasks as you'd like:
Each custom task can be run with:
Transparent Proxy task mode#
For most local documentation, we recommend starting your API application directly with an Optic task, also known as Command Wrapper mode. This allows Optic to start your project and a new capture session to organize observed requests. Sometimes, this isn't feasible - such as when your API is always deployed in a Serverless architecture and cannot be run locally. In this case, the Optic Transparent Proxy mode will let you configure your downstream and upstream URLs.
Setting up the Local CLI in Transparent Proxy mode#
All configuration items for local capture live in the optic.yml file. Create a new task to use the Transparent Proxy mode:
- Create a new task
start-proxyat the same level of indent asstart(the default task). inboundUrl(aliasbaseUrl) is the URL configuration where the application we're observing should expect to live. When using Optic to observe traffic, Optic adopts this URL to intercept traffic and pass it along to the application under observation. That way, your clients or tests can still run exactly as they have in the past.targetUrltells us the target for the observed traffic, our application under observation. We'll need to run the application on this URL so that Optic can pass traffic along to the target application.- The
commandfield is for process wrapping, and isn't necessary for the transparent proxy configuration. Leave that out.
The tasks section of the optic.yml file will look something like this:
Note: if not specified the targetUrl will assume ports based on the protocol (80 for http, 443 for https). It may be optionally omitted in these cases.
Next, run:
This will validate that the configuration is correct. Once the configuration check passes, you can document your API with:
- The local dashboard will be available, with observed diffs.
- The Optic CLI will listen on localhost at the port defined in
inboundUrl. - Traffic sent to the Optic CLI will be forwarded to the defined
targetUrl- assure that is already running, or if not, start it before sending any traffic.
Starting a new Capture Session in Transparent Poxy task mode#
When Optic is started in Transparent Proxy task mode, it is not watching the application lifecycle and does not currently capture rebuild events of the application under observation. To start fresh with a new capture session, stop the current Optic proxy and restart with api run start-proxy. This will create a new capture session in the Optic dashboard and allow you to observe traffic sent to the most recent build of the application under observation.
Dependent tasks#
A task can depend on another task. For example, say you need to start your API service with a task, then want to run test traffic against that service through Optic. First, define the task to start your API service with Optic. Then, define a new task with the command parameter to run your test script and the useTask parameter specifying your service start task. The example below runs a Newman test against the start-proxy task above:
Dependencies can only go one level deep. Dependent tasks cannot define inboundUrls or targetUrls, as dependent tasks expect the API start command to start the Optic proxy and handle these configurations. The dependent task command will run after the API start command starts and the service is responsive. There's no need to add any sleep delays if the service itself takes time to warm up.
Ignoring API Paths#
As you use Optic, you will probably find there are some paths you would like Optic to ignore. These can be identified individually in the undocumented endpoint review page in the UI. For ignoring routes in bulk by some characteristic, you can directly edit the project's ignore rules. Examples include ignoring all OPTIONS requests, .html, .js, .css files, or everything in your /public folder. Many of these are provided by default, and can be removed if necessary.
You can add ignore rules to your .optic/ignore file:
Rules follow the following format:
- The methods component can be:
- a single method
GET - multiple methods
GET POST PUT - omitted -> which is interpreted as
ALL
- a single method
- The path component follows the path-to-regex format. The library has a lot of advanced features that you can use, but most use cases can probably be accomplished with the following patterns:
- Want to ignore an absolute path? Just write it ie
/users/profile - Want to ignore a file type? ie
(.*).png(.*).js - Want to ignore a path and its children?
/public/(.*) - Need something more advanced? Try creating your pattern in the path-to-regex-sandbox
- Want to ignore an absolute path? Just write it ie
- Scalar values in YAML cannot start with a special character (
[] {} > | * & ! % # ` @ ,). If you need to start a value with*, wrap the value in double quotes.