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,

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.

Example of Postman POST

Example of Postman GET

Configure Optic to use Newman

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

      # 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
        command: |
          newman run \
<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 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 (opens in a new tab), or read about creating one here (opens in a new tab).

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!

 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.

Want to ship a better API?

Optic makes it easy to publish accurate API docs, avoid breaking changes, and improve the design of your APIs.

Try it for free