portman

Portman ‍

Port OpenAPI Spec to Postman Collection, with contract & variation tests included!

Portman leverages OpenAPI documents, with all its defined API request/response properties, to power your Postman collection. Let Portman do all the work and inject contract & variation tests with a minimum of configuration. Customize the Postman requests & variables with a wide range of options to assign & overwrite variables.

[!IMPORTANT]
Important Change: If you are using version 1.28.0 with a custom Postman config file specified by the --postmanConfigFile flag, please ensure that the parametersResolution option is set to either "Example" or "Schema". The options requestParametersResolution and exampleParametersResolution are deprecated openapi-to-postman options.

Why use Portman?

Convert your OpenAPI spec to Postman, generate contract & variation tests, upload the Postman collection & run the tests through Newman. Include the Portman CLI as part of an automated process for injecting the power of Portman directly into your CI/CD pipeline.

Read the full blog post

Features

With Portman, you can:

• Convert an OpenAPI document to a Postman collection
  • Support for OpenAPI 3.0
  • Support for OpenAPI 3.1
• Extend the Postman collection with capabilities
  • Inject Postman Contract Tests - learn more
  • Assign collection variables - learn more
  • Inject Postman Variation Tests - learn more
  • Inject Postman Integration Tests
  • Inject Postman with Pre-request & Tests scripts on a collection or operation level - learn more
  • Modify Postman requests - learn more here and here
  • Fuzz Postman requests - learn more
• Upload the Postman collection to your Postman app - learn more
• Test the Postman collection with Newman - learn more
• Split the configuration into multiple files using $ref
• Manage everything in config file for easy local or CI/CD usage - learn more

Getting started

1. Install Portman
2. Initialize Portman CLI configuration by running: $ portman --init

OR

1. Install Portman
2. Copy .env.example to .env and add environment variables you need available to your collection
3. Copy/rename and customize each of the ____.default.json config files in the root directory to suit your needs
4. Start converting your OpenAPI document to Postman

OR

If you have an existing OpenAPI specification, try running Portman without any special setup to see how it can generate a Postman collection with contract tests with it's default configuration.

1. Install Portman
2. Run portman on your OpenAPI spec, ie:

• npx portman -l my-openapi-spec.yaml
• (if your spec is hosted use the -u parameter, ie:
  • npx portman -u https://petstore3.swagger.io/api/v3/openapi.json

This will generate a postman collection that contains a request for every method:endpoint combination defined in your spec, and include a set of "Contract Tests" for each one. You can learn more about contract tests, and how to examine the generated collection here.

(Running portman with no explicit configuration is the same as running it with this configuration file)

All configuration options to convert from OpenAPI to Postman can be found in the openapi-to-postman package documentation. All configuration options to filter flags/tags/methods/operations/... from OpenAPI can be found in the openapi-format package documentation or using the online openapi-format playground.

Installation

Local Installation (recommended)

You can add the Portman CLI to the node_modules by using:

$ npm install --save @apideck/portman

or using yarn:

$ yarn add @apideck/portman

Note that this will require you to run the Portman CLI with npx @apideck/portman -l your-openapi-file.yaml or, if you are using an older version of npm, ./node_modules/.bin/portman -l your-openapi-file.yaml.

Global Installation

$ npm install -g @apideck/portman

NPX usage

To execute the CLI without installing it via npm, use the npx method.

$ npx @apideck/portman -l your-openapi-file.yaml

CLI Usage

…

Environment variables as Postman variables

Portman uses dotenv to not only access variables for functionality, but you can also add environment variables that you'd like declared within your Postman environment. Simply prefix any variable name with PORTMAN_, and it will be available for use in your Postman collection as the camel-cased equivalent. For example:

PORTMAN_CONSUMER_ID=test_user_id

will be available in your collection or tests by referencing:

{{consumerId}}

It is possible to set a spec-specific .env file, that lives next to your config files. The path can be passed in via envFile cli option. This is useful if you have Portman managing multiple specs that have unique environment requirements.

By default, Portman will leverage any ENVIRONMENT variable that is defined that starts with PORTMAN_.

Another option to set variables is by configuring them as collectionVariables in the globals section of your Portman configuration.

CLI Options

Initialize Portman CLI configuration

portman --init

The init option will help you to configure the cliConfig options and put the default config, env file in place to kick-start the usage of Portman.

Pass in the remotely hosted spec

portman -u https://specs.apideck.com/crm.yml

Overwrite the baseUrl in spec and run Newman

portman -u https://specs.apideck.com/crm.yml -b http://localhost:3050 -n true

Path pass to a local data file for Newman to use for iterations

portman -u https://specs.apideck.com/crm.yml -b http://localhost:3050 -n true -d ./tmp/newman/data/crm.json

Pass the path to a local spec (useful when updating your specs) and output Postman collection locally

portman -l ./tmp/specs/crm.yml -o ./tmp/specs/crm.postman.json

Skip tests and just generate collection

portman -l ./tmp/specs/crm.yml -t false

Filter OpenAPI and generate collection

portman -u https://specs.apideck.com/crm.yml --filterFile examples/cli-filtering/oas-format-filter.json

For more details, review the cli-filtering example.

Add extra forms to Json schema validation

portman -l ./tmp/specs/crm.yml -o ./tmp/specs/crm.postman.json --extraUnknownFormats ulid one two

This makes the schema validation more lenient, and solves problems with unknown formats

Upload newly generated collection to Postman, which will upsert the collection, based on the collection name

portman -l ./tmp/specs/crm.yml --syncPostman

Upload newly generated collection to Postman using the collection UID to overwrite the existing.

portman -l ./tmp/specs/crm.yml --syncPostman -p 9601963a-53ff-4aaa-92a0-2e70a8a2a748

When a collection gets large, the Postman API will compare all the requests when updating the collection. This can take some time even result in 5xx errors. To overcome this, you can use the --postmanFastSync option. This option will sync your collection to Postman by using "delete" and "create" operations instead of the "update".

REMARK: Using --postmanFastSync will result in a new Postman collection and Postman UID for each sync.

portman -l ./tmp/specs/crm.yml --syncPostman --postmanFastSync

Portman caches a set of Postman API data to facilitate faster lookups and uploads, preventing unnecessary connecting to the Postman API. In case you need to reset the cache you simply remove the .portman.cache.json file or set the --postmanRefreshCache option when running the Postman sync.

portman -l ./tmp/specs/crm.yml --syncPostman --postmanRefreshCache

Pass custom paths for config files

All configuration options to convert from OpenAPI to Postman can be on the openapi-to-postman package documentation. Portman provides a default openapi-to-postman configuration postman-config.default.json, which will be used if no custom config --postmanConfigFile is passed.

Portman configuration file in JSON format:

portman -u https://specs.apideck.com/crm.yml -c ./tmp/crm/portman-config.json -s ./common/postman-config.json

Portman configuration file in YAML format:

portman -u https://specs.apideck.com/crm.yml -c ./tmp/crm/portman-config.yaml -s ./common/postman-config.json

Pass all CLI options as JSON/YAML file

All the CLI options can be managed in a separate configuration file and passed along to the portman command. This will make configuration easier, especially in CI/CD implementations.

Portman CLI options settings in JSON format

portman --cliOptionsFile ./examples/cli-options/portman-cli-options.json

Portman CLI options settings in YAML format

portman --cliOptionsFile ./examples/cli-options/portman-cli-options.yaml

All the available Portman CLI options can be used in the config file. By passing the CLI options as parameter, you can overwrite the defined CLI options defined in the file.

For more details, review the cli-options example.

Run Newman with Newman options

All Newman configuration options to run Newman can be passed along through Portman.

portman -u https://specs.apideck.com/crm.yml -c ./tmp/crm/portman-config.json --runNewman --newmanOptionsFile ./tmp/crm/newman-options.json

For more details, review the cli-options example.

NOTE: Newman is set to ignore redirects to allow for testing redirect response codes. If you are running collections within Postman UI, you'll need to ensure Postman is set to the same, or your redirect tests will fail.

Postman > Preferences > Automatically follow redirects > OFF

Output

Without specifying the output location, your generated Postman Collection is written to ./tmp/converted/${specName}.json if you are manually importing to Postman or need to inspect for debugging.

By using -o or --output parameter, you can define the location where the Postman collection will be written.

portman -l ./tmp/specs/crm.yml -o ./tmp/specs/crm.Postman.json

Portman settings

The Portman settings consist out of multiple parts:

• version : which refers to the JSON Portman configuration version.
• tests : which refers to the definitions for the generated contract & variance tests.
  • contractTests : refers to the options to enabled autogenerated contract tests.
  • contentTests : refers to the additional Postman tests that check the content.
  • variationTests :