grokify / Swaggman
Projects that are alternatives of or similar to Swaggman
Swaggman - OpenAPI Spec SDK and Postman Converter
Swaggman is a multi-purpose OpenAPI Spec SDK that includes enhanced Postman conversion.
Major Features
- CLI and library to Convert OpenAPI Specs to Postman Collection
- Add Postman environment variables to URLs, e.g. Server URLs like
https://{{HOSTNAME}}/restapi
- Add headers, such as environment variable based Authorization headers, such as
Authorization: Bearer {{myAccessToken}}
- Utilize baseline Postman collection to add Postman-specific functionality including Postman
prerequest
scripts. - Add example request bodies, e.g. JSON bodies with example parameter values.
- Add Postman environment variables to URLs, e.g. Server URLs like
- OpenAPI 3 Spec SDK
- Merge Multiple OAS3 Specs
- Validate OAS3 Specs
- Programmatically examine and modify OAS3 Specs
- Programmatically auto-correct OAS3 Specs
- OpenAPI 2 Spec SDK
- Convert OpenAPI v2 to Postman Collection v2
- Merge Multiple OAS2 Specs
Features
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 functionsimple.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.
Installation
The following command will install the executable binary swaggman
into the ~/go/bin
directory.
$ go get github.com/grokify/swaggman
Usage
Simple Usage
// 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
The following can be added which are especially useful to use with environment variables.
- Custom Hostname
- Custom Headers
// Instantiate a converter with overrides (using Postman environment variables)
cfg := swaggman.Configuration{
PostmanURLBase: "{{RINGCENTRAL_SERVER_URL}}",
PostmanHeaders: []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:
- RingCentral Swagger 2.0 spec
- RingCentral Postman 2.0 base
- RingCentral Postman 2.0 spec - Import this into Postman
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"