Optic documents your APIs as you build them by observing development traffic and learning your API's behavior. The CLI is constantly diffing your API’s behavior against its specification; ensuring every change to the API gets detected, documented and code reviewed by your team.
How does Optic monitor local traffic in Intercept mode? Optic creates a local proxy for your traffic targeting an application. This is often a remote application, such as one deployed behind an Amazon API Gateway, though it can work with any web service. Intercept mode includes flags to set up common tools, such as Chrome, to start using the Optic proxy. When the Optic Intercept session is run with
api intercept <environment> --chrome, for example, Optic will spin up a local proxy and start a new Chrome session that uses the Optic proxy. Traffic to the defined API host is observed and presented to you in the Optic dashboard for documentation.
When would I use intercept mode? Intercept mode is ideal when the project lifecycle is not easily managed with a single command, or the project is located on a remote system (such as behind an Amazon API Gateway). Intercept mode will assist in launching your tools with the proper proxy configurations to make the process as seamless as possible. If your application runs locally and you'd like to test against it, we'd recommend running your API with Optic as it helps manage your project lifecycle and sets up the proxy to be friendly to local tests and workflows. Only use a proxy task for new projects if these other options are not feasible.
Optic environments are configured in the
optic.yml file. This file is created in your API project's root directory when you run
api init. Environments each require a name, and take the following configurations:
- host The API URL. Traffic to this host is observed by Optic and presented to you in the Optic Dashboard to build your documentation.
- webUI The URL which will open in tools such as Chrome. This is the host that provides interactive browsing, such as a web UI. The
hostfield does not determine which traffic will be intercepted.
For example, if you ran
api init and then wanted to set up a production environment to document https://api.github.com and have Chrome start you at https://api.github.com/repos/opticdev/optic, your
optic.yml would look like this:
To start an intercept session, run
api intercept <environment> with your UI as a flag. Currently we recommend Chrome. For example, if you document the GitHub API in the production environment defined above using Chrome, you would see the following:
Optic will show you the most recent request made, and the status code. It keeps a running tally of requests collected. When you're finished, terminate the Optic session with
ctrl+c. The session will end. When using Chrome as in this example, it will close the browser window that is set to use the Optic proxy as well to avoid any confusion. Continue on to create your initial API specification with the data collected from