Easy-Bake: from Postman Collection to OpenAPI

Create an OpenAPI specification in a Hasbro minute

Do you need an OpenAPI definition for a project, but don’t have one? If you have a Postman collection, you can create an OpenAPI definition in one command.

The OpenAPI specification has multiple benefits when used with RESTful APIs. The standardization it provides, the ability to generate interactive documentation, and the built in interoperability are just a few of its benefits.

Postman has recently exposed the collection transformation endpoint in the Postman API. This lets us easily generate an OpenAPI definition from a Postman Collection.

Creating an OpenAPI Definition From a Collection With the Postman API | Postman Blog

Some quick steps:

Step 1
You will need a Postman API key. If you haven’t done that yet, in Postman, click your avatar in the upper right corner, select Settings, and then API keys. You can generate a new one and copy the API key to a safe location.

Step 2
Now get the collection id of the Postman collection you want to transform. You can get this by clicking the info icon (letter i inside a circle) in the right hand toolbar. In this picture, it is at the bottom right.

Step 3
Now you’re ready for the easy part. The command below will call the collection transformation endpoint and return a response body. Jq formats the output into a JSON file. You will need jq (https://github.com/jqlang/jq) installed before running this command.

curl --location --request GET 'https://api.getpostman.com/collections/{{collectionId}}/transformations' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{postman-api-key}}' \
| jq '.output | fromjson' \
> my_openapi.json

Lo and behold, we have an OpenAPI definition. Almost as groovy as a cake cooked with a light bulb. I’m using mine to test out Azure’s Defender for API — let you know how that goes.