Creating an OpenAPI definition from a collection with the Postman API

David Espi Hernandez

October 26, 2023

Postman’s integrated API Builder lets you design your APIs with an API definition. But even with the help of the API Builder, creating an OpenAPI definition can be difficult. On the other hand, it’s easier to create collections in Postman. Postman Collections make it easy to add requests, create JSON response and request bodies, and even get information from existing servers with Postman Live Collections.

We recently exposed the collection transformation endpoint in the Postman API, which helps bridge the gap between the API Builder and Postman Collections and makes it easier to create an API-first design. Simply call the endpoint and you will get a response that contains your collection’s OpenAPI definition.

With this endpoint, you can:

• Use collections as a tool for your API-first design. You can design your API in a collection, add the corresponding examples, share it with your stakeholders, and create mock servers. Once the API design is approved, you can use this endpoint to convert your collection to an OpenAPI definition.
• Automatically convert a collection into an OpenAPI definition and programmatically sync the API definition in Postman.

In this post, we’ll show you how you can use the new Postman API endpoint to easily turn your collections into OpenAPI definitions you can use with Postman’s API Builder.

Step 1: Get the collection’s OpenAPI definition with the Postman API

First, run the following command, replacing {{collectionId}} with your collection’s ID and {{postman-api-key}} with your Postman API key value:

curl --location --request GET 'https://api.getpostman.com/collections/{{collectionId}}/transformations' \

--header 'Content-Type: application/json' \

--header 'x-api-key: {{postman-api-key}}'

This command calls the collection transformation endpoint and returns a response body similar to the following:

{"output":"{\"openapi\":\"3.0.3\",\"info\":{\"title\":\"Blogpost: convert collection into OpenAPI\",\"version\":\"1.0.0\"},\"servers\":[{\"url\":\"https://postman-echo.com\"}],\"paths\":{\"/get\":{\"get\":{\"tags\":[\"default\"],\"summary\":\"Retrieve resource\",\"parameters\":[{\"name\":\"queryParam\",\"in\":\"query\",\"schema\":{\"type\":\"string\"},\"example\":\"value\"}],\"responses\":{\"200\":{\"description\":\"OK\",\"headers\":{\"Date\":{\"schema\":{\"type\":\"string\",\"example\":\"Tue, 19 Sep 2023 07:55:16 GMT\"}},\"Content-Type\":{\"schema\":{\"type\":\"string\",\"example\":\"application/json; charset=utf-8\"}},\"Content-Length\":{\"schema\":{\"type\":\"integer\",\"example\":\"455\"}},\"Connection\":{\"schema\":{\"type\":\"string\",\"example\":\"keep-alive\"}},\"ETag\":{\"schema\":{\"type\":\"string\",\"example\":\"W/\\\"1c7-uf8/UqqY3lVr9ce8gw2ezu2U6bA\\\"\"}},\"set-cookie\":{\"schema\":{\"type\":\"string\",\"example\":\"sails.sid=s%3ASfWFAgot9KIrPVWc1LFU9epZytyvAMzh.5h4u9nIlNba1z%2F%2Fcyc21Qym8MIzrDQ68R%2BzyTgZVH%2Bk; Path=/; HttpOnly\"}}},\"content\":{\"application/json\":{\"schema\":{\"type\":\"object\"},\"example\":{\"args\":{\"queryParam\":\"value\"},\"headers\":{\"x-forwarded-proto\":\"https\",\"x-forwarded-port\":\"443\",\"host\":\"postman-echo.com\",\"x-amzn-trace-id\":\"Root=1-650953e4-6ae9504466614d120d93feb1\",\"user-agent\":\"PostmanRuntime/7.33.0\",\"accept\":\"*/*\",\"postman-token\":\"1a1e92e9-e27c-4b7c-9854-420db16e6262\",\"accept-encoding\":\"gzip, deflate, br\"},\"url\":\"https://postman-echo.com/get?queryParam=value\"}}}}}}},\"/post\":{\"get\":{\"tags\":[\"default\"],\"summary\":\"Create resource\",\"responses\":{\"404\":{\"description\":\"Not Found\",\"headers\":{\"Date\":{\"schema\":{\"type\":\"string\",\"example\":\"Tue, 19 Sep 2023 07:56:03 GMT\"}},\"Content-Length\":{\"schema\":{\"type\":\"integer\",\"example\":\"0\"}},\"Connection\":{\"schema\":{\"type\":\"string\",\"example\":\"close\"}},\"set-cookie\":{\"schema\":{\"type\":\"string\",\"example\":\"sails.sid=s%3AhbKkbH0EoTr-OyyTjQMnC1Cntxxy2EM5.o1yU%2FgQzMnS5GL8S%2FbGODfPy9gn3qOpIVY1Wd%2BxjMjk; Path=/; HttpOnly\"}}},\"content\":{\"text/plain\":{\"schema\":{\"type\":\"string\"},\"example\":null}}}}}}}}"}

The output field in the endpoint’s response contains the generated OpenAPI 3.0.3 definition in a stringified format.

Step 2: Extract and format the response’s text with jq

Next, we’ll want to extract the output field from the response and save it to a file in JSON format. We’ll use jq to do this in the following 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'

In this command, we’re sending the collection transformation’s output contents and piping it to jq with the jq '.output | fromjson' command. The jq command extracts the output field, then reads the JSON string with the fromjson jq function. Note that all the jq arguments are enclosed in single quote (') characters.

When you run this command, it prints a properly-formatted JSON object:

Step 3: Save the OpenAPI definition to a file

Lastly, we’ll dump the output from jq into a JSON file:

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

In this step, we’re directing the output from jq to a file. This file contains the formatted OpenAPI definition generated from the given collection ID. You can then use this file to create an API definition in Postman’s API Builder:

Next steps

This is just an example of how you can create an OpenAPI definition from a collection and use it. Do you have a specific use case? How do you design and develop your APIs? Are you using the API design-first approach? Let us know in the comments!