Capturing Traffic

Optic Capture helps create OpenAPI specifications and keep them up to date by examining the traffic to your API. Under the hood the following happens when running Capture,

Your API is started via a command you provide.
A reverse proxy is configured to send traffic to your API.
A command or set of requests you provide is run, generating traffic to the proxy.
Optic observes the traffic as it passes through the proxy.
These observations can then be used to create or update your OpenAPI specification.

💡

By default, all of this happens locally. Your capture details and API specification are not sent to Optic unless you explicitly opt into uploading your results to Optic Cloud.

You can view the capture CLI options with,

optic capture --help

Configuration

Capture is configured inside your optic.yml file. Whether or not you already have an optic.yml, getting started is easy via the optic capture init command.

You can insert a configuration block into your optic.yml (generating one if necessary) with a complete, commented configuration example:

optic capture init [./path/to/your/]openapi.yml

Configuration Reference

optic capture init can also display a capture configuration example to stdout, making it a useful reference and source of truth for the Capture configuration options. For example, the following command will display the configuration block without making any changes to optic.yml.

optic capture init --stdout openapi.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
    # At least one of 'requests.run' or 'requests.send' is required below.
    requests:
      # Run a command to generate traffic. Requests should be sent to the Optic proxy, the address of which is injected
      # into 'run.command's env as OPTIC_PROXY or the value of 'run.proxy_variable', if set.
      run:
        # The command that will generate traffic to the Optic proxy. Globbing with '*' is supported.
        # Required if specifying 'requests.run'.
        command: your-test-command
        # The name of the environment variable injected into the env of the command that contains the address of the Optic proxy.
        # Optional: default: OPTIC_PROXY
        proxy_variable: OPTIC_PROXY
      # Have Optic generate traffic to the proxy itself by specifying endpoint details. A request's 'data' attribute
      # is converted to JSON and sent along with the request.
      send:
        # path: Required
        # method: Optional: default: GET
        # data: Optional: If omitted on a POST request, default: {}
        # headers: Optional: If 'content-type' is omitted, it is set to 'application/json;charset=UTF-8'.
        - path: /
          method: GET
        - path: /users/create
          method: POST
          headers:
            content-type: application/json;charset=UTF-8
          data:
            name: Hank
    config:
      # The number of parallel requests to make when using 'requests.send'.
      # Optional: default: 4
      request_concurrency: 4

Once you've set up your capture configuration you're ready to update, create, and verify your OpenAPI spec!

Create/Update an OpenAPI spec

You can persist changes to (or create) your OpenAPI spec by including --update <mode> in your capture command.

➜ optic capture openapi.yml --update automatic
Initializing OpenAPI file at openapi.yml
✔ Successfully captured requests
 
Learning path patterns for unmatched requests...
Documenting new operations:
✔ GET /
✔ GET /users
✔ POST /users/create

There are 3 update modes,

mode	description
interactive	Interactively prompt and confirm observed changes to new and existing endpoints.
automatic	Automatically apply observed changes to new and existing endpoints.
documented	Automatically apply observed changes to existing endpoints only.

Verify an OpenAPI spec

If you already have an OpenAPI spec and run capture without the --update <mode> option, the requests observed will be compared against your spec without making changes to it.

$ optic capture openapi.yml
✔ Successfully captured requests
✖ GET /
  200 response
  [404 response body] body is not documented
✔ GET /users
  ✓ 200 response
✔ POST /users/create
  ✓ Request Body, ✓ 201 response

Next Steps

View examples generating traffic to Optic, or import existing requests from HAR files or Postman collections.

CLI Reference Examples