swaggman

package module
v0.0.0-...-998eeed Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 22, 2017 License: MIT Imports: 8 Imported by: 0

README

Swaggman - Swagger to Postman Converter

Go Report Card Docs License

swaggman is an API specification converter that creates a Postman 2.0 Collection spec from a Swagger (OAI) 2.0 spec.

Features

  • Supports Postman scripts by accepting an optional base Postman 2.0 spec that contains information not readily stored in Swagger Spec to support functions such as OAuth Password Grant.
  • Supports override URL hostname parameter to support a Postman environment variable for the URL hostname, e.g. https://{{MY_HOSTNAME}}/restapi
  • Supports additional headers, e.g. authorization headers using enviroment variables, e.g. Authorization: Bearer {{myAccessToken}}

These are all used in the included example discussed below.

Additional discussion is available on Medium.

Notes

  • Postman 4.10.7 does not natively support JSON requests so request bodies need to be entered using the raw body editor. A future task is to add Swagger request examples as default Postman request bodies.
  • Postman 2.0 spec supports polymorphism and doesn't have a canonical schema. For example, the request.url property can be populated by a URL string or a URL object. Swaggman uses the URL object since it is more flexible. The function simple.NewCanonicalCollectionFromBytes(bytes) can be used to read either a simple or object based spec into a canonical object spec.
  • This has only been used on the RingCentral Swagger spec to date but will be used for more in the future. Please feel free to use and contribute. Examples are located in the examples folder.

Usage

Simple Usage

import(
	"github.com/grokify/swaggman"
)

// Instantiate a converter with default configuration
conv := swaggman.NewConverter(swaggman.Configuration{})

// Convert a Swagger spec
err := conv.Convert("path/to/swagger.json", "path/to/pman.out.json")

Usage with Features

import(
	"github.com/grokify/swaggman"
	"github.com/grokify/swaggman/postman2"
)

// Instantiate a converter with overrides (using Postman environment variables)
cfg := swaggman.Configuration{
	PostmanURLHostname: "{{RC_SERVER_HOSTNAME}}",
	PostmanHeaders: []postman2.Header{postman2.Header{
		Key:   "Authorization",
		Value: "Bearer {{my_access_token}}"}}}
conv = swaggman.NewConverter(cfg)

// Convert a Swagger spec with a default Postman spec
err := conv.MergeConvert("path/to/swagger.json", "path/to/pman.base.json", "path/to/pman.out.json")

Example

An example conversion is included, examples/ringcentral/convert.go which creates a Postman 2.0 spec for the RingCentral REST API using a base Postman 2.0 spec and the RingCentral basic Swagger 2.0 spec.

A video of importing the resulting Postman collection is available on YouTube.

Example files include:

The RingCentral spec uses the following environment variables. The following is the Postman bulk edit format:

RC_SERVER_HOSTNAME:platform.devtest.ringcentral.com
RC_APP_KEY:myAppKey
RC_APP_SECRET:myAppSecret
RC_USERNAME:myMainCompanyPhoneNumber
RC_EXTENSION:myExtension
RC_PASSWORD:myPassword

For multiple apps or users, simply create a different Postman environment for each.

To set your environment variables, use the Settings Gear icon and then click "Manage Environments"

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildPostmanURL

func BuildPostmanURL(cfg Configuration, swag swagger2.Specification, swaggerURL string, endpoint swagger2.Endpoint) postman2.URL

BuildPostmanURL creates a Postman 2.0 spec URL from a Swagger URL

func Convert

Convert creates a Postman 2.0 collection from a configuration and Swagger 2.0 spec

func Merge

Merge creates a Postman 2.0 collection from a configuration, base Postman 2.0 collection and Swagger 2.0 spec

func Swagger2PathToPostman2APIItem

func Swagger2PathToPostman2APIItem(cfg Configuration, swag swagger2.Specification, url string, method string, endpoint swagger2.Endpoint) postman2.APIItem

Swagger2PathToPostman2APIItem converts a Swagger 2.0 path to a Postman 2.0 API item

Types

type Configuration

type Configuration struct {
	PostmanURLHostname string            `json:"postmanURLHostname,omitempty"`
	PostmanHeaders     []postman2.Header `json:"postmanHeaders,omitempty"`
}

Configuration is a Swaggman configuration that holds information on how to create the Postman 2.0 collection including overriding Swagger 2.0 spec values.

type Converter

type Converter struct {
	Configuration Configuration
	Swagger       swagger2.Specification
}

Converter is the struct that manages the conversion.

func NewConverter

func NewConverter(cfg Configuration) Converter

NewConverter instantiates a new converter.

func (*Converter) Convert

func (conv *Converter) Convert(swaggerFilepath string, pmanSpecFilepath string) error

Convert builds a Postman 2.0 spec using a Swagger 2.0 spec.

func (*Converter) MergeConvert

func (conv *Converter) MergeConvert(swaggerFilepath string, pmanBaseFilepath string, pmanSpecFilepath string) error

MergeConvert builds a Postman 2.0 spec using a base Postman 2.0 collection and a Swagger 2.0 spec.

Directories

Path Synopsis
examples

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL