Creating an OpenAPI definition can be difficult, and it’s often 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 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 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. 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: This command calls the collection transformation endpoint and returns a response body similar to the following: 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: 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: 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: 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! David Espi Hernandez David Espi Hernandez is a technical product manager at Postman. View all posts by David Espi Hernandez → What do you think about this topic? Tell us in a comment below.

Comment Cancel reply This site uses Akismet to reduce spam. Learn how your comment data is processed. 11 thoughts on “ Creating an OpenAPI definition from a collection with the Postman API ” I executed the following in Command Prompt in Windows and didn’t work. How can I solve this?: curl –location –request GET “https://api.getpostman.com/collections/{{collectionId}}/transformations” ^ More? –header “Content-Type: application/json” ^ More? –header “x-api-key: {{Collection Access Key( can be obtained when “Export” and share “Via API)}}” {“type”:”https://api.postman.com/problems/forbidden”,”title”:”Forbidden”,”detail”:”Forbidden”,”status”:403} Please contact our support team at http://www.postman.com/support and they’ll be able to help you. I dont see the responses being generated. I just see below where as in the image shown, the responses are extracted. Please tell me what am i missing here. “responses”: { “200”: { “description”: “” } } Please contact our support team at http://www.postman.com/support and they’ll be able to help you. Could you please open this endpoint up for public collections? This would make it much simpler to integrate with Postman. It is quite confusing, that you have to fork it first and then use your own collection-id. Why can’t postman provide endpoint’s response as OpenAPI 3.0.3 definition in a JSON format . The GET request seems to time out after 60 seconds. I tried it on my collection with this: curl -m 3600 –location –request GET ‘https://api.getpostman.com/collections/{{my-collection-id}}/transformations’ –header ‘Content-Type: application/json’ –header ‘x-api-key: {{my-key}}’ It returned: % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 0 0 0 0 0 0 0 0 –:–:– 0:01:00 –:–:– 0 Please contact our support team at http://www.postman.com/support and they’ll be able to help you. Well, this seems a bit complex… Would it be possible to offer OpenAPI as an collection export format ? With all necessary warnings and disclaimer if any… Is there a way to do this without being logged in and using a workspace? Thanks! Hi, Please contact our support team at http://www.postman.com/support and they’ll be able to help you. You might also like Headless Postman: Automating the API Lifecycle with the MCP Server Most API developers have a familiar routine: open Postman, import a spec, create some requests, wire up a mock, run tests, check… Postman as a Local Development Environment Postman has always been the platform where API development comes together — from firing off test requests to validating response contracts. With… Querying the Postman Context Graph with the AI Engineer Ask the Postman AI Engineer questions about your APIs and services. See what the Context Graph knows about ownership, consumers, drift, and duplication. The world's APIs are built and shipped on Postman.