Converting OpenAPI Specs to Postman Collections

Abhijit Kane

January 5, 2019

Postman first introduced support for importing Swagger 1.0/2.0 specs over 3 years ago. At the time, the Postman collection format was basic – features like multi-level folder support and collection variables didn’t exist. The imports were lossy as many features from Swagger couldn’t be reasonably mapped to Postman.

After the first OpenAPI spec was released in mid-2017, the Postman community started expressing the need for OpenAPI support. Specifically, being able to import OpenAPI specs into Postman and use them as collections. Internally, we wanted to wait till our roadmap for plugins was clearer before beginning development. At the same time, this let us examine new use-cases as the OAS 3.0 spec was iterated on.

We started development on OpenAPI import support a few months ago, and you can start using it today on Postman. You can find a guide to importing OpenAPI specs on our blog. We’re iterating on this fast, so feel free to reach out on our public issue tracker if you notice something not importing correctly, or an alternative approach to converting any part of the spec.

Some of the concepts and OpenAPI features that we wanted to preserve during the conversion:

1. API Structure: The OAS spec lists API endpoints according to the path property. Postman supports a multi-level folder structure to organize requests in a collection. The current converter creates a new level of hierarchy for each URL segment. Of course, /if/a/url/like/this leads to only one endpoint, 5 levels of folders are not created. This approach led to a reasonable folder structure for most OAS specs we tested. We’re exploring other strategies to create folders – using operation tags, for example.
2. Schemas: The OpenAPI spec describes schemas for specific objects that are reused throughout the API (in the request/response body and headers, for example). These are used in the generated collection to describe requests and responses better.
3. Flexibility: Different OAS specs address different use-cases. To support these, many decisions made by the converter are configurable. As plugin support grows in Postman, these settings will be accessible through the app. We plan to expose folder generation strategies, request naming strategies, schema faking as settings soon.
4. Reusability: The OAS spec supports reusability of certain values (the base URL, for example). One objective of the OpenAPI→Postman conversion was to preserve this – we avoid storing the server’s URL in the request when we can use a variable and store the value only in the collection.
5. Completeness: Taking advantage of as many OpenAPI features as we could to generate a meaningful Postman collection was a priority. Apart from the basic list of endpoints, the converter also generates request examples and maintains descriptions for URL parameters/headers.

A drill-down into the conversion process:

1. Validation: This involves checking the input against known constraints of the OAS spec – the root info, openapi, and paths properties must be present, and that info must have a title and version. This is just intended to ensure we’re dealing with an OAS3.0 spec, and not validate the input against the entire OAS schema. The converter tries to follow Postel’s Law as far as possible, resulting in graceful failures for specs that don’t adhere to the schema in certain areas.
2. Scaffolding: Generate a trie-type structure for all paths in the OAS spec. This lets us go through all paths before computing the folder structure for the generated collection. By and large, we generate a new folder for each segment of path encountered.
3. Collection backbone: Add folders and requests to the collection from the trie. A folder is created for any path prefix with 2 or more leaf nodes.
4. Request conversion: The method, URL, and headers are straightforward to compute. We generate the request name from the operation summary (we fall back to the operation ID or URL). This is internally exposed as an option (available if you use the converter as an independent node module). One challenge was the request body, where we need to generate a sample body based on the schema provided. For url-encoded data, the converter supports the array/spaceDelimited/pipeDelimited/deepObject styles as described in the spec. For JSON, we generate a sample body that conforms to the provided schema. The latest Postman Canary also supports the generation of XML request/response bodies.

Future plans:

1. Multi-file support: This will let us import folders (or archives) that contain modularised specs (the API structure in one file and the components in another, for example).
2. Handling remote references: Some specs reference schemas hosted on the web, which makes the main spec file smaller (the relevant schemas can be pulled on-demand). The current version of the converter ignores these remote references, but we plan to expose support for these via an option soon.
3. Generating multiple collections/environments: Variables defined in the OAS spec are presently saved as collection variables. However, it might make sense to move some variables (sensitive keys, for example) to environments. The converter’s return format already supports conversion to multiple Postman entities, so this change is backward-compatible.
4. Tags: Exposing an option to let the folder structure be constructed according to tags, not just the path.

We’ve open-sourced the converter on Github. This lets us take contributions from the active OpenAPI community and aggregate discussions around improving the state of OpenAPI tooling. We plan to move the other conversion plugins we’re working on to Github too – these include the curl and RAML importers in Postman!

Stay tuned to our community for more chatter on this!