swagger2-postman-generator

A simple interface for converting Swagger v2 JSON Specs to a Postman Collection, with samples of Swagger request models added as JSON request bodies.

Based on the swagger2-to-postman NPM package and Swagger UI JSON example request generator.

Features:

• Import Swagger Spec direct from URL, JSON file, raw JSON string and JavaScript object

• Export Postman Collection to JavaScript object, raw JSON, JSON file or via a HTTP POST

• Export Postman Environment with all URL parameters and other variables - can be exported to JavaScript object, raw JSON, JSON file or via a HTTP POST

• Base URLs for endpoints are made generic with Postman environment placeholders for scheme (HTTP/HTTPS), host (some.website.com) and port (8080) -> http://some.website.com/api/do/stuff becomes {{scheme}}://{{host}}:{{port}}/api/do/stuff

Base URL parameters are included in any generated postman envrionment file

NPM Package: https://www.npmjs.com/package/swagger2-postman-generator GitHub: https://github.com/djfdyuruiry/swagger2-postman-generator

This package is part of a collection of three Swagger v2 converters I have created:

• swagger2-to-object: NPM | GitHub
• swagger2-to-json: NPM | GitHub

---

Install

1npm install swagger2-postman-generator

---

Usage

This NPM module returns a single object which is used to access a chain of different import and generate functions. Import the module like so:

1var Swagger2Postman = require("swagger2-postman-generator");
2
3Swagger2Postman
4    .convertSwagger()
5    // do more stuff...

Importing Swagger

This can then be followed by an import function

Import Swagger URL

1Swagger2Postman
2    .convertSwagger()
3    .fromUrl("http://petstore.swagger.io/v2/swagger.json")

Import Swagger JSON File

1Swagger2Postman
2    .convertSwagger()
3    .fromFile("swagger.json")

Import Swagger JSON String

1Swagger2Postman
2    .convertSwagger()
3    .fromJson('{"swagger":"2.0",...')

Import Swagger JavaScript Object

1var swaggerSpec = getSwaggerSpecFromSomewhere(); // example
2
3Swagger2Postman
4    .convertSwagger()
5    .fromSpec(swaggerSpec)

Exporting Postman

Once you have imported a Swagger spec, you have several options for generating the Postman collection output.

Export to Postman JSON

1var collectionJson = Swagger2Postman
2    .convertSwagger()
3    .fromUrl("http://petstore.swagger.io/v2/swagger.json")
4    .toPostmanCollectionJson()

Export to Postman JSON File

1Swagger2Postman
2    .convertSwagger()
3    .fromFile("swagger.json")
4    .toPostmanCollectionFile("postman_collection.json")

Export to Postman JavaScript object

1var collection = Swagger2Postman
2    .convertSwagger()
3    .fromJson('{"swagger":"2.0",...')
4    .toPostmanCollection()

Export Postman via HTTP POST

1var swaggerSpec = getSwaggerSpecFromSomewhere(); // example
2
3Swagger2Postman
4    .convertSwagger()
5    .fromSpec(swaggerSpec)
6    .toPostmanCollectionPost("https://some.web.service/api/postman/collections")

Export Postman Environment

You can export a auto-generated Postman Environment JSON that contains the host, port, scheme and all the distinct parameters found in the Swagger spec.

1var swagger2Postman = Swagger2Postman
2    .convertSwagger()
3    .fromJson('{"swagger":"2.0",...')
4    
5var options = getOptionsFromSomewhere(); // options for postman collection and environment
6
7var env = swagger2Postman
8    .toPostmanEnvironment(options)
9
10var json = swagger2Postman
11    .toPostmanEnvironmentJson(options)
12
13swagger2Postman
14    .toPostmanEnvironmentFile("env.json", options)
15
16swagger2Postman
17    .toPostmanEnvironmentPost("https://some.web.service/api/postman/environments", options)

---

Options

You can pass an options object to the from and to functions as the last parameter. No specific options are supported yet for from functions.

Note when dealing with a Postman request body, URL or headers you can use the environment variable syntax to add placeholders; e.g. token: {{tokenVariable}}

from and to options

• debug: set this flag to true to turn on console logging of library calls, for debugging purposes only

to function options

• requestPreProcessor: function that receives the postman request and swagger spec, called before request URL and body are processed

1Swagger2Postman
2    .convertSwagger()
3    .fromFile("swagger.json")
4    .toPostmanCollection({
5        requestPreProcessor: (postmanRequest, swaggerSpec) => {
6            // postmanRequest - request object from postman collection
7            // swaggerSpec - Swagger spec object used to generate postman collection
8        }
9    })

Postman request objects look like this:

1{
2			"name": "OAuth1.0 Verify Signature",
3			"dataMode": "params",
4			"data": [
5				{
6					"key": "code",
7					"value": "xWnkliVQJURqB2x1",
8					"type": "text",
9					"enabled": true
10				}
11			],
12			"rawModeData": "{\"some\":\"json\"}",
13			"descriptionFormat": null,
14			"description": "OAuth1.0a is a specification that defines....",
15			"headers": "Authorization: OAuth\n",
16			"method": "GET",
17			"pathVariables": {},
18			"url": "https://echo.getpostman.com/oauth1",
19			"preRequestScript": "",
20			"tests": "responseCode.code === 200",
21			"currentHelper": "normal",
22			"helperAttributes": {}
23		}

In the request rawModeData is the request body as a string, and data is form data. A full schema for Postman v1 collections can be found here

• globalHeaders: array of literal HTTP headers to add to all requests (useful for authentication headers etc.) e.g. Authorization: Basic {{base64Credentials}}

1Swagger2Postman
2    .convertSwagger()
3    .fromFile("swagger.json")
4    .toPostmanCollection({
5        globalHeaders: [
6            "DNT: 0",
7            "Authorization: Basic {{usernamePasswordBase64}}" // you can use postman variables here
8        ]
9    })

• requestPostProcessor: function that receives the postman request and swagger spec, called after request URL and body are processed

1Swagger2Postman
2    .convertSwagger()
3    .fromFile("swagger.json")
4    .toPostmanCollection({
5        requestPostProcessor: (postmanRequest, swaggerSpec) => {
6            // postmanRequest - request object from postman collection
7            // swaggerSpec - Swagger spec object used to generate postman collection
8
9            if (postmanRequest.url.includes("/some/special/route")) {
10                // add extra form data and a custom header to a special route (e.g. login)
11                postmanRequest.data.push({
12                    "key": "someFormField",
13                    "value": "someFormValue",
14                    "type": "text",
15                    "enabled": true
16                });
17
18                postmanRequest.headers += "Cache-Control: no-cache\n";
19            }
20        }
21    })

• postJsonBuilder: a function that receives the postman collection as JSON and returns a custom JSON string to use as the POST body (only for toPostmanCollectionPost and toPostmanEnvironmentPost)

1Swagger2Postman
2    .convertSwagger()
3    .fromFile("swagger.json")
4    .toPostmanCollectionPost("https://some.web.service/api/postman/collections", {
5        postJsonBuilder: (postmanCollectionJson) => {
6            // postmanCollectionJson - the postman collection as JSON
7
8            // do some things here...
9
10            return postmanCollectionJson;
11        }
12    })

• prettyPrint: boolean which when set to true will pretty print Postman JSON output (does not apply to toPostmanCollection)

1Swagger2Postman
2    .convertSwagger()
3    .fromFile("swagger.json")
4    .toPostmanCollection({
5        prettyPrint: true
6    })

Options for Postman Environments

These options only apply when calling toPostmanEnvironment[Json|File|Post] functions.

• environment.name: the name of the Environment shown in Postman UI

1Swagger2Postman
2    .convertSwagger()
3    .fromFile("swagger.json")
4    .toPostmanEnvironment({
5        environment: {
6            name = "Environment Name"
7        }
8    })

• environment.customVariables: list of custom variables to add to Environment

1Swagger2Postman
2    .convertSwagger()
3    .fromFile("swagger.json")
4    .toPostmanEnvironment({
5        environment: {
6            customVariables = [{ // list of custom variables to add
7                name = "accessCode",
8                value = "9283928", // optional, default is blank string
9                enabled = true, // optional, default is true (shows as check box in Postman UI)
10                type = "text" // optional, default is text
11            }]
12        }
13    })