# Creating an OpenAPI definition from a collection with the Postman API

Creating an [OpenAPI](https://swagger.io/specification/) definition can be difficult, and it's often easier to create collections in Postman. [Postman Collections](https://learning.postman.com/docs/collections/collections-overview/) make it easy to add requests, create JSON response and request bodies, and even get information from existing servers with [Postman Live Collections](https://learning.postman.com/docs/collections/live-collections/live-collections-overview/). We recently exposed the [collection transformation](https://www.postman.com/postman/workspace/postman-public-workspace/request/12959542-aeceb96d-2ba6-48ea-b0df-71661491dac3) endpoint in the Postman API, which helps bridge the gap between API definitions 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](https://www.postman.com/api-platform/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](https://www.postman.com/postman/workspace/postman-public-workspace/request/12959542-4fff4089-9529-41c9-9ceb-58253e5cb342) in Postman.
 
 In this post, we’ll show you how you can use the new Postman [API endpoint](https://blog.postman.com/what-is-an-api-endpoint/) to easily turn your collections into OpenAPI definitions. ## 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](https://blog.postman.com/what-is-json/#:~:text=The%20Postman%20Team,machines%20can%20write%20and%20read.) format. We’ll use [jq](https://jqlang.github.io/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: ![A terminal displaying the jq command and its formatted JSON object response](https://blog.postman.com/wp-content/uploads/2023/10/2064-get-collections-output-300x263.jpg)## 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: ![A view of the generated OpenAPI in Postman](https://blog.postman.com/wp-content/uploads/2023/10/2064-oas-in-api-builder-300x187.jpg)## 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!