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.
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
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_KEYenvironment variable. Below we’ll demonstrate running Optic while setting a value for that variable.
requests.run.commandwe use Newman’s
--env-varproperty to set the Postman variable
URLto the value of
OPTIC_PROXYis an environment variable containing the URL of Optic’s capture proxy. Optic observes traffic that passes through the proxy.
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 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
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.