Skip to main content

CLI Commands


oas [openapi-file] status --har <captured-har>

Matches captured traffic against the OpenAPI specification. Provide an OpenAPI file and a HAR with API traffic.

oas openapi.yaml status --har traffic.har

Matched Operations
GET /todos
GET /todos/{todoId}
PATCH /todos/{todoId}/status

Undocumented methods
POST /todos

Undocumented paths
GET /lists

oas [openapi-file] add [--har captured-har]

Adds a new Operation to your OpenAPI specification. If you pass in a HAR with matching requests, Optic will document the API request and responses.

You can document one operation at a time ie GET /lists, several GET /lists, POST /lists, and also multiple methods at once GET,POST /lists. Tip: you can copy paste method + path combinations straight from the output of oas status.

If you need to document a path parameter, wrap it in {path_parameter} ie GET /lists/{list_id}/settings. Optic will document the new path and the path parameters properly in the specification.

oas openapi.yaml add --har traffic.har GET /lists

» added GET /lists

oas [openapi-file] update [--har captured-har] [--proxy hostname]

Keeps your OpenAPI specification updated and accurate, by adapting it to describe your API's traffic. Reviewing the changes Optic made before checking them in can also help to verify changes to your API were as intended. Most users open their Git client OR by run optic diff openapi.yml to visualize the effective Optic diff.

» GET /todos - 10 patches applied

1 matched / 2 total observed requests
Finished and applied patches

In addition to HARs, this command can accept traffic captured directly from a man-in-the-middle proxy, allowing you to always run it against the latest version of your API without risk of stale HARs or any extra steps. For more details, see Capturing traffic below.

oas new [openapi-file]

Creates an empty OpenAPI file.

oas new openapi.yml

 ✓ New spec file created at ~/Desktop/openapi.yml

Capturing traffic

Most of the oas commands take a HAR (HttpArchive) file as one of their inputs. These tools interpret the traffic logged in these files as the actual behaviour of your API. When adding-to or updating your OpenAPI specification, this is what allows it to make sure the specification is up-to-date and an accurate description of your API.

There are many ways to log your API traffic as a HAR.

  • Chrome can export HARs containing the contents of the Network Tab in developer tools.
  • Many API frameworks support logging tools HARs from your test traffic.
  • Put a MITM (man-in-the-middle) proxy in front of your service.

oas capture --proxy [hostname] [output-file]

This command starts a man-in-the-middle proxy on an available port (defaults to 8000) that routes traffic to the [hostname] you provided. Requests / responses are written as HAR to a file when a filename is supplied as an argument, or otherwise piped to stdout.