Using Optic Capture with Postman

Using Capture with Postman Collections

optic capture generates and updates OpenAPI specs based on real traffic. Most teams use their integration tests as a traffic source. Optic also has built-in support for using Traffic from Postman.

Using Saved Examples from Postman

If you save examples in your Postman collections, you can export the collection and analyze it with through Optic Capture

You can export a collection by following these docs from Postman

optic capture openapi.yml --postman ./postman-collection.json

✔ GET /
  ✓ 200 response
✔ GET /users
  ✓ 200 response
✔ POST /users/create
  ✓ 201 response

Running Newman

Inside your application directory, create an optic.yml file with contents similar to,

capture:
  openapi.yml:
    server:
      # the command to start your application
      command: go run main.go
      # the url where your application is listening. Optic will forward requests
      # from the proxy to this URL.
      url: http://localhost:8080
    requests:
      run:
        command: |
          newman run \
          https://api.getpostman.com/collections/<collection_uuid>?apikey=$POSTMAN_API_KEY \
          --env-var URL=$OPTIC_PROXY

There are a few things worth mentioning about this file:

• <collection_uuid> should be replaced with the UUID of your Postman collection.
• A Postman API key is required to access a private collection from the CLI. In the above example, we reference the key from the POSTMAN_API_KEY environment variable. Below we’ll demonstrate running Optic while setting a value for that variable.
• In requests.run.command we use Newman’s --env-var property to set the Postman variable URL to the value of OPTIC_PROXY. OPTIC_PROXY is an environment variable containing the URL of Optic’s capture proxy. Optic observes traffic that passes through the proxy.

You will need a Postman API Key for the next step. If you need to create one, you can do so here, or read about creating one here.

Run Optic Capture

Now that the pieces are in place, all that’s left to do is run Optic Capture with optic capture openapi.yml --update interactive. Optic will create an OpenAPI specification named openapi.yml (you can give it a different name if you wish), and prompt you to confirm each endpoint it observes.

Below, we first export a variable name POSTMAN_API_KEY. The value of the variable is passed through to Newman, allowing it to authenticate the collection request with the Postman API. We export the variable in our shell for brevity, but you can use any method that makes the variable available to the Optic process.

CALLOUT: Don’t commit your Postman API key to source control!

➜ export POSTMAN_API_KEY=PMAK-...
➜ optic capture openapi.yml --update interactive
Initializing OpenAPI file at openapi.yml
...
✔ Finished running requests

Learning path patterns for unmatched requests...
> /
✔ Is this the right pattern for GET / › yes
> /users
✔ Is this the right pattern for GET /users › yes
> /users/create
✔ Is this the right pattern for POST /users/create › yes
Documenting new operations:
✔ GET /
✔ POST /users/create
✔ GET /users

Take a look in the openapi.yml file and admire your OpenAPI spec!

Making Changes

Making changes is as simple as updating your app and/or Postman collection and rerunning Optic. Any new or changed endpoints will be added!

For example, if we add a department field for our users, Optic will update our OpenAPI spec when we run it again,

➜ optic capture openapi.yml --update interactive
...
✔ Finished running requests
✔ GET /
  ✓ 200 response
✔ POST /users/create
  ✓ Request Body, ✓ 201 response
  [request body] 'department' has been added (/properties/department)
  [201 response body] 'department' has been added (/properties/department)
✔ GET /users
  ✓ 200 response