Generate OpenAPI from Postman Collections

Nate Meyer 2023-10-20

Postman (opens in a new tab) is a popular web-based API development tool. Collections of replayable API requests are great to have during development, but they are not a substitute for great API docs. This tutorial shows you how to use the Optic and the Postman CLI tool, Newman (opens in a new tab), to generate and maintain accurate OpenAPI documentation from the data in your Postman collections (opens in a new tab).

Before we get started it’s assumed that you have,

• Installed Optic (opens in a new tab).
  • npm -g install @useoptic/optic, or sh -c "$(curl -Ls https://install.useoptic.com/install.sh)"
• Signed up for a Postman (opens in a new tab) account.
• Installed Newman (opens in a new tab), Postman’s CLI tool.

Define your API

Here we’ve defined a simple API a few endpoints. Note that we’ve used Postman’s environment variable syntax to reference a variable named URL.

Configure Optic to use 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 (opens in a new tab) 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.

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

Final Thoughts

We walked through a simple example demonstrating how to integrate Optic into your API workflow with Postman. Optic and Postman are complementary tools well suited for building and maintaining APIs. Adding Optic to your workflow helps you ship your API with the confidence it is working as designed.

Optic is useful when run locally, but consider adding it to your CI workflow (opens in a new tab) for even more benefit. Optic is a powerful tool for detecting changes and enforcing API standards across your team as well.