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 with the --stdout argument, making it a useful starting point. For more advanced use, here is a feature-complete Capture configuration example.

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
 
    # One of 'requests.run' or 'requests.send' is required.
    requests:
      # Run an external command to generate traffic.
      run:
        # The command to run to generate traffic (e.g., your test command, etc.).
        command: your-test-command
 
        # The name of the environment variable injected into the env of 'command' that contains the address of the Optic proxy.
        # Optional: default: OPTIC_PROXY
        proxy_variable: OPTIC_PROXY
 
      # Use Optic to generate requests.
      send:
        - path: /users/create # Required
          method: POST # Optional: default: GET
          headers: # Optional
            content-type: application/json;charset=UTF-8 # If omitted, this is the default
          data: # Optional: If omitted on a POST request, default: {}
            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.

Document Existing API Examples