Faria Rehman November 22, 2018

API Transformer Recipes: Enabling Postman’s Team Sharing Features for OpenAPI Users

This blog is the first of many to come as part of my new series called “API Transformer Recipes”. The series aims to highlight numerous ways in which developers can integrate API Transformer into their workflow in order to gain access to a wide range of tools and frameworks. Hopefully, it will help eliminate any assumptions that they have about being restricted to a particular set of tools just because they use a certain API specification format.

Are you an OpenAPI user looking to use Postman somewhere in your development pipeline but don’t really know how? Well, then, you are in the right place. In this blog, I will show you how being an OpenAPI user (or a Swagger one if you prefer the old name) should not stop you from taking advantage of some of the very powerful team collaboration Postman features.

Postman Team Collaboration Features

Postman’s easy-to-use and rich interface attracts a large number of users. If you have a team working on APIs, it offers team workspaces to let your team efficiently and effectively collaborate over those APIs while establishing a single source of truth.

Postman Team Collaboration Features

Postman has also exposed their API using which you and your team members can easily push the latest collections/API specifications from within your applications.

From OpenAPI to Postman

 OpenAPI is a preferred choice of the majority of the users out there due to its extensive support of a wide range of APIs and a strong community. While there are tools out there that support team collaboration for OpenAPI files e.g.  SwaggerHub, it may be that you are on the lookout for alternatives. Reasons that are purely dependent on personal preferences, the type of project you are working on, or the size of your team. So if you maintain your specs in OpenAPI but are looking to use Postman, simply including API Transformer in your workflow will help achieve your goal.

One of our customers Phil Sturgeon, who works at WeWork, maintains specs in OpenAPI but uses Postman to share them with his team. To streamline this workflow, he makes use of API Transformer. You can check out his blog here to learn more.

Deep Dive Into the Flow

The steps discussed below demonstrate the use of APIs for converting your files and pushing them to Postman. However, if you have quite a few files that need processing you can opt to use the GUIs instead. It is entirely up to you.

OpenAPI to Postman Workflow

From OpenAPI to Postman: Complete Workflow

The steps involved for you to convert your OpenAPI files to a Postman-compatible format are simply:

Step 1: Collect your OpenAPI files

Collect all OpenAPI files you intend to use in Postman. These can be new or updated versions of the existing ones. Pass them one by one as input to the next step.

Step 2: Transform each file using API Transformer

The Postman app and API accept Postman schema files as import formats. To use an OpenAPI file in Postman you would, therefore, need to convert it to an appropriate version of the Postman schema file. This is where API Transformer comes into play which supports both schema versions 1.0 and 2.0.

So as part of this step, to convert your file, you will need to use the appropriate API Transformer endpoint from the CodeGen and Transformer API. Pass OpenAPI file as input along with Postman chosen as the output format (v1.0 or v2.0). If the file is valid, the API will respond with the Postman file which you can then pass on to the next step.

Step 3: Push each Postman Schema File to Postman

This step involves the use of Postman API to push each of the transformed files into Postman. Once that is done, Postman will automatically sync this file for all the team members giving them the latest view instantly.

And that’s about it. It is as simple as enabling Postman’s team sharing features for OpenAPI users.

Continue reading:
a) Part 2 of API Transformer Recipes — Facilitating Migration from SOAP to REST
b) Part 3 of API Transformer Recipes — Opening ways into IBM API Connect
c) Part 4 of API Transformer Recipes — Moving to GraphQL from SOAP or REST
d) Part 5 of API Transformer Recipes — The Whys and Hows of Exposing a SOAP Service Using Your REST API