Auto Sync Microservices Swagger Docs Into Postman Collection

Introduction

Swagger has become the de facto standard for defining REST APIs and modern development workflows often auto-generate Swagger documentation directly from code.

While Swagger is highly effective, its user experience falls short compared to Postman.

On the other hand Postman cannot auto-generate collections from code, but it allows users to import Swagger definitions through its UI.

However, this method is manual and time-consuming — nobody wants to spend time syncing Swagger manually.

In this blog, we are going to solve this problem by auto syncing swagger definitions into a postman collection, which can be added in your CI pipeline to improve develop experience.

So let’s get started.

Note: We will be dealing with swagger 2.0, this solution is not tested with other swagger versions.

Pre Requisites

To achieve this result, the following pre-requisites must be met

1. Swagger Files — You should have the required swagger files that needs to be synced to postman collection. Alternatively, you can follow this guide which provides test swagger files for demonstration.
2. Node.js & NPM Installed — Required for running automation scripts
3. Account created on postman.com

With the pre-requisites elucidated, Let’s understand the application

Introduction to the Application

We will be working with a microservices architecture which includes four services: Accounts, Cards, Masters, and Transfer Service. Each service’s APIs begin with a base path prefix, /api/v1/<service-name>, enabling the API gateway to route requests based on the path.

Follow the below steps to download swagger files of our microservices application.

1. Clone the repository
   git clone git@github.com:sharadregoti/try-out.git
2. Navigate to this directory
   cd try-out/08-microservices/auto-sync-postmand-collection
3. Swagger files will be present at services/<service-name>/docs directory

That’s all about the application, but there is a problem. The script that we are using for swagger to postman conversion, converts one swagger doc to its individual postman collection. Meaning if I have 25 microservices, I have to deal with 25 postman collection. But i don’t want this behavior, I want a single collection for all my microservices. That’s why I’ll be merging multiple swagger docs into a single swagger doc.

Note: Merging of swagger docs is not required for a monolithic application.

Combining Swagger

We will be using a Node.js module called combine-swagger for this purpose.

This utility is straightforward to use, simply supply a configuration file referencing the necessary swagger files to merge, and optionally, include additional configurations to modify behavior.

Let’s install it on our machine using NPM. Execute the below command to install this package globally.

npm install -g swagger-combine

Once the package is installed, create a file named swagger-combine-config.json with the below content.

Note: We are assuming you are insidetry-out/08-microservices/auto-sync-postmand-collection directory

{
    "swagger": "2.0",
    "info": {
        "title": "demo",
        "version": "1.0.0"
    },
    "host": "{{host}}",
    "schemes": [
        "https"
    ],
    "apis": [
        {
            "url": "./services/account-service/docs/swagger.json",
            "paths": {
                "useBasePath": true
            },
            "tags": {
                "add": [
                    "account-service"
                ]
            }
        },
        {
            "url": "./services/card-service/docs/swagger.json",
            "paths": {
                "useBasePath": true
            },
            "tags": {
                "add": [
                    "card-service"
                ]
            }
        },
        {
            "url": "./services/transfer-service/docs/swagger.json",
            "paths": {
                "useBasePath": true
            },
            "tags": {
                "add": [
                    "transfer-service"
                ]
            }
        },
        {
            "url": "./services/master-service/docs/swagger.json",
            "paths": {
                "useBasePath": true
            },
            "tags": {
                "add": [
                    "master-service"
                ]
            }
        }
    ]
}

This configuration outlines the setup for a Demo App using Swagger 2.0, specifying basic details like the version, title, and supported schemes (HTTPS). It includes paths to swagger files for combining services: Accounts, Cards, Transfer, and Masters. Each service’s API uses a base path for routing, indicated by “useBasePath”: true. The host field is set to {{host}} to allow for variable substitution with postman environment variables, facilitating dynamic host URL configuration. You can replace it with a static host URL such as appdev.com.

For more configuration options, checkout the documentation on Github.

Now, execute the below command to generate the combined swagger file.

swagger-combine swagger-combine-config.json -o swagger.json

Copy the content of generated swagger file swagger.json and validate it on Swagger Editor.

You should observed no errors, except the one shown in the below image due to our host value {{host}}

With the combined swagger generated, Let’s sync it to postman

Auto Sync Postman

Syncing a swagger doc to a postman collection is a 4 step process

1. Create an empty collection on postman (this will hold the swagger APIs)
2. Generate the postman API keys (required for authentication)
3. Fork the postman APIs & get the collection ID of your newly created collection
4. Execute the script to convert swagger to postman collection and push it to your postman workspace via API.

Generate Postman API Keys

To interact with postman programmatically, we require API keys for authentication. Follow the below steps to generate API keys.

1. Open postman and go to settings as shown in the below image

1. Then go to the API section and generate an API key

1. Copy the API Key and store it somewhere

Create an Empty Collection on Postman

I have logged into my postman account & created a postman collection called demo (create it in your personal workspace)

Fork the Postman Public APIs & get the Collection ID of your newly created Collection

The nodejs script requires the ID of the newly created postman collection, to get the ID we will use postman APIs. Follow the below steps to get the collection ID.

1. Open this Postman API collection on browser and fork it in you workspace.

1. Open the forked collection from your workspace & set the postman API Keys as described in the below image.

1. Send the API Request In the forked collection, Open the Get all collections API (under collections folder) & hit send. Analyze the response and extract the collection id and uid of your newly created collection (demo).

Execute the Swagger to Postman Collection Conversion Script

The postman team has created a nodeJS package swagger2-postman2 that converts swagger file to a postman collection. I have created a script that uses the aforementioned package for converting swagger doc to postman collection and then it pushes the result to postman workspace. Follow the below steps to execute the automation script.

1. Clone the repository

git clone https://github  .com/sharadregoti/convert-swagger-2.0-to-postman-v2-and-push.git
cd convert-swagger-2.0-to-postman-v2-and-push/

1. Copy swagger.json file inside convert-swagger-2.0-to-postman-v2-and-push directory
2. Update Configuration
   Update config.js in the directory by replacing its content with the configuration below. The from attribute specifies the Swagger documentation file, while to designates the output Postman collection file. collection_uid and collection_id are identifiers for the collection to be updated, replace this with values obtained from previous steps.

var secret = require('./secrets.js');

module.exports = {
    "collections": [
        {
            "from": "swagger",
            "to": "postman-collection",
            "name": "Demo",
            "collection_uid": "<replace-this-with-your-collection-uid>",
            "collection_id": "<replace-this-with-your-collection-id>"
        }
    ],
    "key": secret.key
};

1. Run the Script
   Execute the below commands to run the script.

npm install
export POSTMAN_API_KEY="<replace-this-with-your-postman-api-key>"
node converter.js

1. Observe Result on Postman App
   Go to the postman app and check the collection, it should be updated as shown in the below image.

Now you can define the variables such as host at postman collection or environment level and execute the requests.

CD Pipeline

You can go one step further and add this automation process to your CD pipeline. This will ensure whenever developer makes changes in swagger, the same gets reflected into postman collection.

Useful Tips

1. Swagger is the Source of Truth Running the converter.js script will overwrite any manual edits in the Postman collection, including name changes, request modifications, or configuration adjustments.
2. Leverage Postman Collection and Environment Variables The script variabilizes hosts, query parameters, and path parameters. Assign values to these variables at the collection or environment level in Postman; the script preserves these values without alterations.
3. API Authentication Set authentication at the collection level initially; it won’t be overwritten by subsequent script runs and will be inherited by all APIs. Use a consistent authentication method across APIs to ensure inheritance. If different APIs require different authentication methods, setting them at the request or folder level is possible, but be aware these settings will reset with each script execution.

That’s it in this blog post, If you liked this blog post. You can follow me on Twitter or Youtube where I talk about Microservices, Cloud, Kubernetes & Golang.