Keep Calm and convert Swagger APIs to Postman Collections

If you are here, you already know what a piece of beauty Swagger is. But let me brief it a bit again. Swagger is an Interface Description Language for describing RESTful APIs expressed using JSON. Swagger can be used together with a set of open-source software tools to design, build, document, and use RESTful web services. Swagger includes automated documentation, code generation, and test-case generation. Seems like all good stuff.

Now, while Swagger may contains multiple tools in itself to design, create and setup RESTful services for an application, today I am interested in Swagger UI.

Swagger UI lets you visualize and interact with the API’s resources without having any of the implementation logic in place, making it easy for back end implementation and client side consumption, in short, provides a portal for users to interact with the REST APIs directly.

A sample Swagger UI for a test application

I, being a VMware Cloud Developer, am very well aware of the Swagger UI as VMware uses Swagger framework quite extensively in most of their applications and tools. However, the reason I am writing this article is the annoyance caused by the variations of this framework in these VMware tools. I realized over time that the implementation of Swagger UI is not consistent in all the VMware tools. For example, The way you login in one toolset is way different than other tools or the way you interact with APIs in one toolset is way different than other tools etc. This really gets my nerve when I have to develop and try to fetch something from a particular tool only to find out that either I am not authorized to call a service or the body I am sending is not good enough to response me back something useful because I forget the sequence of steps to make it work. All I get are errors 401, 403, 501 or 202 and what not. Sometimes, even getting the URL to open Swagger UI becomes cumbersome.

Hence, If any reader is facing any similar issue or just want to consistent and start from where he left, I would suggest convert these Swagger UIs to Postman APIs. Postman not only saves the progress & credentials but also let you save the example to assist you with what you did last time.

Frankly, It saves me lot of time.

Let’s take an example to a backup application NSS from Veritas. Follow the steps to convert:

Open the Swagger UI portal

https://<nss_fqdn>/NetBackupSelfServiceNetBackupPanels/api/help/index

Copy the link from which the Swagger UI is fetching its resources. This link is almost always mentioned on the Swagger UI page itself.
Open that link to validate, you should see a large JSON in your browser.

https://<nss_fqdn>/NetBackupSelfServiceNetBackupPanels/api/docs/v6

Open Postman app or web app, go to your workspace and click Import

Select Link and paste the link which you validated to see the huge JSON

If the link you provided is correct, you would see something like this.

Click Submit and your import is complete. You may close this dialog box now.

When import is complete, you will see all the REST calls are available at your disposal, just like you have them in Swagger UI. But much more organized with all the documentation and examples already imported. That’s so cool.

You can change play with option Postman provide while you import from a link and set them as suits you.

Important Note: Postman can sync your environment credentials on its server. Although they claim to store them in encrypted format (Source: postman.com Data at rest – Depending on its sensitivity classification, customer data is also AES-256-GCM encrypted on the server-side before storage), but if you or your organization have a requirement to prevent your data from being synced to the Postman cloud to avoid any compliance issues, you can use Postman without signing into an account and manually back up your data locally.

Postman indicates the sync state of your workspace. The flow diagram for sync states is shown below:

If you are not signed in to Postman, you see the state as Offline.

Or if you really have to login into Postman, I would suggest to land your confidential data in CURRENT VALUE field and not in ~~INITIAL VALUE~~ as it clearly says they never get synced.