swagger2-postman-generator
v2.1.5
Published
Use Swagger v2 JSON Collections to generate Postman v1 collections which include sample request bodies
Downloads
1,769
Readme
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:
Install
npm 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:
var Swagger2Postman = require("swagger2-postman-generator");
Swagger2Postman
.convertSwagger()
// do more stuff...
Importing Swagger
This can then be followed by an import function
Import Swagger URL
Swagger2Postman
.convertSwagger()
.fromUrl("http://petstore.swagger.io/v2/swagger.json")
Import Swagger JSON File
Swagger2Postman
.convertSwagger()
.fromFile("swagger.json")
Import Swagger JSON String
Swagger2Postman
.convertSwagger()
.fromJson('{"swagger":"2.0",...')
Import Swagger JavaScript Object
var swaggerSpec = getSwaggerSpecFromSomewhere(); // example
Swagger2Postman
.convertSwagger()
.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
var collectionJson = Swagger2Postman
.convertSwagger()
.fromUrl("http://petstore.swagger.io/v2/swagger.json")
.toPostmanCollectionJson()
Export to Postman JSON File
Swagger2Postman
.convertSwagger()
.fromFile("swagger.json")
.toPostmanCollectionFile("postman_collection.json")
Export to Postman JavaScript object
var collection = Swagger2Postman
.convertSwagger()
.fromJson('{"swagger":"2.0",...')
.toPostmanCollection()
Export Postman via HTTP POST
var swaggerSpec = getSwaggerSpecFromSomewhere(); // example
Swagger2Postman
.convertSwagger()
.fromSpec(swaggerSpec)
.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.
var swagger2Postman = Swagger2Postman
.convertSwagger()
.fromJson('{"swagger":"2.0",...')
var options = getOptionsFromSomewhere(); // options for postman collection and environment
var env = swagger2Postman
.toPostmanEnvironment(options)
var json = swagger2Postman
.toPostmanEnvironmentJson(options)
swagger2Postman
.toPostmanEnvironmentFile("env.json", options)
swagger2Postman
.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 totrue
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
Swagger2Postman
.convertSwagger()
.fromFile("swagger.json")
.toPostmanCollection({
requestPreProcessor: (postmanRequest, swaggerSpec) => {
// postmanRequest - request object from postman collection
// swaggerSpec - Swagger spec object used to generate postman collection
}
})
Postman request objects look like this:
{
"name": "OAuth1.0 Verify Signature",
"dataMode": "params",
"data": [
{
"key": "code",
"value": "xWnkliVQJURqB2x1",
"type": "text",
"enabled": true
}
],
"rawModeData": "{\"some\":\"json\"}",
"descriptionFormat": null,
"description": "OAuth1.0a is a specification that defines....",
"headers": "Authorization: OAuth\n",
"method": "GET",
"pathVariables": {},
"url": "https://echo.getpostman.com/oauth1",
"preRequestScript": "",
"tests": "responseCode.code === 200",
"currentHelper": "normal",
"helperAttributes": {}
}
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}}
Swagger2Postman
.convertSwagger()
.fromFile("swagger.json")
.toPostmanCollection({
globalHeaders: [
"DNT: 0",
"Authorization: Basic {{usernamePasswordBase64}}" // you can use postman variables here
]
})
requestPostProcessor
: function that receives the postman request and swagger spec, called after request URL and body are processed
Swagger2Postman
.convertSwagger()
.fromFile("swagger.json")
.toPostmanCollection({
requestPostProcessor: (postmanRequest, swaggerSpec) => {
// postmanRequest - request object from postman collection
// swaggerSpec - Swagger spec object used to generate postman collection
if (postmanRequest.url.includes("/some/special/route")) {
// add extra form data and a custom header to a special route (e.g. login)
postmanRequest.data.push({
"key": "someFormField",
"value": "someFormValue",
"type": "text",
"enabled": true
});
postmanRequest.headers += "Cache-Control: no-cache\n";
}
}
})
postJsonBuilder
: a function that receives the postman collection as JSON and returns a custom JSON string to use as the POST body (only fortoPostmanCollectionPost
andtoPostmanEnvironmentPost
)
Swagger2Postman
.convertSwagger()
.fromFile("swagger.json")
.toPostmanCollectionPost("https://some.web.service/api/postman/collections", {
postJsonBuilder: (postmanCollectionJson) => {
// postmanCollectionJson - the postman collection as JSON
// do some things here...
return postmanCollectionJson;
}
})
prettyPrint
: boolean which when set to true will pretty print Postman JSON output (does not apply totoPostmanCollection
)
Swagger2Postman
.convertSwagger()
.fromFile("swagger.json")
.toPostmanCollection({
prettyPrint: true
})
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
Swagger2Postman
.convertSwagger()
.fromFile("swagger.json")
.toPostmanEnvironment({
environment: {
name = "Environment Name"
}
})
environment.customVariables
: list of custom variables to add to Environment
Swagger2Postman
.convertSwagger()
.fromFile("swagger.json")
.toPostmanEnvironment({
environment: {
customVariables = [{ // list of custom variables to add
name = "accessCode",
value = "9283928", // optional, default is blank string
enabled = true, // optional, default is true (shows as check box in Postman UI)
type = "text" // optional, default is text
}]
}
})