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:

• <input checked="" disabled="" type="checkbox"> Convert an OpenAPI document to a Postman collection
  • <input checked="" disabled="" type="checkbox"> Support for OpenAPI 3.0
  • <input checked="" disabled="" type="checkbox"> Support for OpenAPI 3.1
• Extend the Postman collection with capabilities
  • <input checked="" disabled="" type="checkbox"> Inject Postman Contract Tests - learn more
  • <input checked="" disabled="" type="checkbox"> Assign collection variables - learn more
  • <input checked="" disabled="" type="checkbox"> Inject Postman Variation Tests - learn more
  • <input checked="" disabled="" type="checkbox"> Inject Postman Integration Tests
  • <input checked="" disabled="" type="checkbox"> Inject Postman with Pre-request & Tests scripts on a collection or operation level - learn more
  • <input checked="" disabled="" type="checkbox"> Modify Postman requests - learn more here and here
  • <input checked="" disabled="" type="checkbox"> Fuzz Postman requests - learn more
• <input checked="" disabled="" type="checkbox"> Upload the Postman collection to your Postman app - learn more
• <input checked="" disabled="" type="checkbox"> Test the Postman collection with Newman - learn more
• <input checked="" disabled="" type="checkbox"> Split the configuration into multiple files using $ref
• <input checked="" disabled="" type="checkbox"> 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:
3. npx portman -l my-openapi-spec.yaml
4. (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

Usage: -u <url> -l <local> -b <baseUrl> -t <includeTests>

Options:
 --help                     Show help                                                                        [boolean]
 --version                  Show version number                                                              [boolean]
 --url,-u                   URL of OAS to port to Postman collection                                         [string]
 --local, -l                Use local OAS to port to Postman collection                                      [string]
 --baseUrl, -b              Override spec baseUrl to use in Postman                                          [string]
 --output, -o               Write the Postman collection to an output file                                   [string]
 --oaOutput                 Write the (filtered) OpenAPI file to an output file                              [string]
 --runNewman, -n            Run Newman on newly created collection                                           [boolean]
 --newmanRunOptions         JSON stringified object to pass options for configuring Newman                   [string]
 --newmanOptionsFile        Path/URL to Newman options file to pass options for configuring Newman           [string]
 --newmanIterationData, -d  Iteration data to run Newman with newly created collection                       [string]
 --localPostman             Use local Postman collection, skips OpenAPI conversion                           [string]
 --syncPostman              Upload generated collection to Postman (default: false)                          [boolean]
 --syncPostmanCollectionIds Synchronises the IDs of newly created postman collections with those already
                            on Postman, useful when you want to use Postman pull request (default: false)    [boolean]
 --postmanFastSync          Postman sync creates new collection (new UID),instead of update (default: false) [boolean]
 --postmanRefreshCache      Postman sync will refresh all local cached Postman API data (default: false)     [boolean]
 --postmanUid, -p           Postman collection UID to upload with the generated Postman collection           [string]
 --postmanWorkspaceName     Postman Workspace name to target the upload of the generated Postman collection  [string]
 --includeTests, -t         Inject Portman test suite (default: true)                                        [boolean]
 --bundleContractTests      Bundle Portman contract tests in a separate folder in Postman (default: false)   [boolean]
 --portmanConfigFile, -c    Path/URL to Portman settings config file (portman-config.json)                   [string]
 --postmanConfigFile,-s     Path to openapi-to-postman config file (postman-config.json)                     [string]
 --filterFile               Path/URL to openapi-format config file (oas-format-filter.json)                  [string]
 --envFile                  Path to the .env file to inject environment variables                            [string]
 --collectionName           Overwrite OpenAPI title to set the Postman collection name                       [string]
 --cliOptionsFile           Path/URL to Portman CLI options file                                             [string]
 --ignoreCircularRefs       Ignore circular references in OpenAPI spec (default: false)                      [boolean]
 --logAssignVariables       Toggle logging of assigned variables (default: true)                             [boolean]
 --warn/--no-warn           Toggle warnings for missing openApiOperationIds (default: true)                  [boolean]
 --init                     Configure Portman CLI options in an interactive manner                           [string]
 --extraUnknownFormats      Add extra unknown formats to json schema tests                                   [array]

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 : refers to the options to define variation tests.
  • integrationTests : refers to the options to define integration tests.
  • extendTests : refers to the custom additions of manually created Postman tests.
• assignVariables : which refers to setting Postman collection variables for easier automation.
• overwrites : which refers to the custom additions/modifications of the OpenAPI/Postman request data.
• operationPreRequestScripts : which refers to injecting Postman Pre-request Scripts for requests.
• globals : which refers to the customization that applies for the whole Postman collection.

Portman targeting

It is possible to inject Postman tests and pre-register scripts, assign variables and overwrite query params, headers, request body data with values.

To be able to do this very specifically, there are options to define the targets:

• openApiOperationId (String) : References to the OpenAPI operationId, example: leadsAll
• openApiOperationIds (Array) : References to an array of OpenAPI operationIds, example: ['leadsAll', 'companiesAll', 'contactsAll']

• openApiOperation (String) : References to a combination of the OpenAPI method & path, example: GET::/crm/leads

• excludeForOperations (Array) : References to OpenAPI operations that will be skipped for targeting. It supports both the openApiOperationId and openApiOperation format, example: ["leadsAdd", "GET::/crm/leads/{id}"]

An openApiOperationId is an optional property. To offer support for OpenAPI documents that don't have operationIds, we have added the openApiOperation definition, which is the unique combination of the OpenAPI method & path, with a :: separator symbol. The targeting option excludeForOperations is really useful when using wildcards, to allow exclusions from the wildcard.

This will allow targeting for very specific OpenAPI items.

To facilitate managing the filtering, we have included wildcard options for the openApiOperation option, supporting the methods & path definitions.

REMARK: Be sure to put quotes around the target definition.

• Strict matching example: "openApiOperation": "GET::/crm/leads", This will target only the "GET" method and the specific path "/crm/leads"

• Method wildcard matching example: "openApiOperation": "*::/crm/leads", This will target all methods ('get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace') and the specific path "/crm/leads"

• Path wildcard matching example: "openApiOperation": "GET::/crm/*" This will target only the "GET" method and any path matching any folder behind the "/crm", like "/crm/companies" and "/crm/leads".

• Method & Path wildcard matching example: "openApiOperation": "*::/crm/*", A combination of wildcards for the method and path parts is even possible.

Portman - tests properties

The Portman tests is where you would define the tests that would be applicable and automatically generated by Portman, based on the OpenAPI document. The contract tests are grouped in an array of contractTests.

contractTests options

• openApiOperationId (String) : References to the OpenAPI operationId. (example: leadsAll)
• openApiOperationIds (Array) : References to an array of OpenAPI operationIds, example: ['leadsAll', 'companiesAll', 'contactsAll']
• openApiOperation (String) : References to a combination of the OpenAPI method & path (example: GET::/crm/leads)
• excludeForOperations (Array | optional) : References to OpenAPI operations that will be skipped for targeting, example: ["leadsAdd", "GET::/crm/leads/{id}"]
• openApiRequest (String | optional) : References to the OpenAPI request body content-type (supports wildcards like application/*) to use for the contract test. If not defined, the default request content-type from OpenAPI will be used, with a preference for application/json.

• openApiResponse (String | optional) : References to the OpenAPI response object code or code::content-type (supports wildcards like text/*) for which a contract test will be inserted. Examples: "404", "200::text/plain", "200::text/*". If not defined, the 1st response object from OpenAPI will be taken as expected response.

  Contract tests are always attached to the main request that Portman generates for an operation. When your OpenAPI document lists multiple request or response content types, only one set will be used for that request. You can control which types are selected with the openApiRequest and openApiResponse options. To create individual requests for every content type, use the variation testing concept described below.

• statusSuccess (Boolean) : Adds the test if the response of the Postman request returned a 2xx

• statusCode (Boolean, HTTP code) : Adds the test if the response of the Postman request return a specific status code.
• responseTime (Boolean) : Adds the test to verify if the response of the Postman request is returned within a number of ms.
  • maxMs (number) : Define the expected number of ms for the responseTime check.
• contentType (Boolean) : Adds the test if the response header is matching the expected content-type defined in the OpenAPI spec.
• jsonBody (Boolean) : Adds the test if the response body is matching the expected content-type defined in the OpenAPI spec.
• schemaValidation (Boolean) : Adds the test if the response body is matching the JSON schema defined in the OpenAPI spec. The JSON schema is inserted inline in the Postman test.
  • additionalProperties (Boolean) : Extend the expected JSON schema used for the schemaValidation by setting all the additionalProperties.
• headersPresent (Boolean) : Adds the test to verify if the Postman response header has the required header names present, like defined in the OpenAPI spec.

For more details, review the contract-tests example and the testsuite-contract-content-types example for some more details about targeting request body & response content-types.

variationTests options

• openApiOperationId (String) : References to the OpenAPI operationId for which a variation will be created. (example: leadsAll)
• openApiOperationIds (Array) : References to an array of OpenAPI operationIds, example: ['leadsAll', 'companiesAll', 'contactsAll']
• openApiOperation (String) : References to a combination of the OpenAPI method & path for which a variation will be created. (example: GET::/crm/leads)
• excludeForOperations (Array | optional) : References to OpenAPI operations that will be skipped for targeting, example: ["leadsAdd", "GET::/crm/leads/{id}"]
• openApiResponse (String | optional) : References to the OpenAPI response object code or code::content-type. Supports wildcards for both the code (e.g. 4* or *) and the content type (e.g. text/* or *). Examples: "404", "200::text/plain", "2*::application/json", "2*::application/*", "*::*". If not defined, the 1st response object from OpenAPI will be taken as expected response. If the configured response code is not defined in the OpenAPI document, Portman will not generate a variation for the targeted operations.

• openApiRequest (String | optional) : References to the OpenAPI request body content-type (supports wildcards like application/*) for which a variation will be created. If not defined, the default request content-type from OpenAPI will be used.

• overwrites : which refers to the custom additions/modifications of the OpenAPI/Postman request data, specifically for the variation.

• fuzzing : Fuzz testing sets unexpected values for API requests, to cause unexpected behavior and errors in the API response.
• tests : which refers to the definitions for the generated contract & variance tests for the variation.
  • contractTests : refers to the options to enabled autogenerated contract tests for the variation.
  • contentTests : refers to the additional Postman tests that check the content for the variation.
  • extendTests : refers to the custom additions of manual created Postman tests to be included in the variation.
• assignVariables : This refers to setting Postman collection variables that are assigned based on variation.

For more details, review the content-variation example and the content-type variation example.

integrationTests options

• name (String) : As Integration tests will normally contain multiple operations, this is the folder name that will be generated in the Integration Tests folder in your Postman collection.
• operations (Array) : Array of operations to be performed

Portman - contentTests properties

Content tests will validate if the response property values will match the expected defined values. While the Portman tests verify the "contract" of the API, the contentTests will verify the content of the API.

contentTests options

• openApiOperationId (String) : References to the OpenAPI operationId. (example: leadsAll)
• openApiOperationIds (Array) : References to an array of OpenAPI operationIds, example: ['leadsAll', 'companiesAll', 'contactsAll']
• openApiOperation (String) : References to a combination of the OpenAPI method & path (example: GET::/crm/leads)

• excludeForOperations (Array | optional) : References to OpenAPI operations that will be skipped for targeting, example: ["leadsAdd", "GET::/crm/leads/{id}"]

• responseBodyTests (Array) : Array of key/value pairs of properties & values in the Postman response body.

  • key (String) : The key that will be targeted in the response body to check if it exists.
    • To look up a key within in array of objects, you can use an array index (example data.websites[0].url) or a * wildcard (example: data.websites[*].url) which uses the value to match an object in an array.
    • To test a response body that is a single value instead of a JSON object, set this to '.'
  • value (String) : The value that will be used to check if the value in the response body property matches.
  • contains (String) : The value that will be used to check if the value is present in the value of the response body property.
  • oneOf (String[],Number[],Boolean[]) : The value that will be used to check one of the values is matching the response body property.
  • length (Number) : The number that will be used to check if the value of the response body property (string/array) has a length of the defined number.
  • minLength (Number) : The number that will be used to check if the value of the response body property (string/array) has a minimum length of the defined number.
  • maxLength (Number) : The number that will be used to check if the value of the response body property (string/array) has a maximum length of the defined number.
  • notExist (Boolean) : The inverse of the key check that verify if the key does not exist in the response body.
  • assert (String) : A custom Postman assertion to check if the value in the response body property matches with the provided assertion (example: not.to.be.null).

• responseHeaderTests (Array) : Array of key/value pairs of properties & values in the Postman response header.

  • key (String) : The header name that will be targeted in the response header to check if it exists.
  • value (String) : The value that will be used to check if the value in the response header matches.
  • contains (String) : The value that will be used to check if the value is present in the value of the response header.
  • oneOf (String[],Number[],Boolean[]) : The value that will be used to check one of the values is matching the value of the response header.
  • length (Number) : The number that will be used to check if the value of the response header has a length of the defined number of characters.
  • minLength (Number) : The number that will be used to check if the value of the response header has a minimum length of the defined number of characters.
  • maxLength (Number) : The number that will be used to check if the value of the response header has a maximum length of the defined number of characters.
  • notExist (Boolean) : The inverse of the key check that verify if the key does not exist in the response header.
  • assert (String) : A custom Postman assertion to check if the value in the response header matches with the provided assertion (example: not.to.be.null).

For more details, review the content-tests example.

Portman - extendTests properties

When you need to add additional tests or overwrite the Portman-generated test, you can use the extendTests to define the raw Postman tests. Anything added in the tests array will be added to the Postman test scripts.

extendTests options

• openApiOperationId (String) : References to the OpenAPI operationId. (example: leadsAll)
• openApiOperationIds (Array) : References to an array of OpenAPI operationIds, example: ['leadsAll', 'companiesAll', 'contactsAll']
• openApiOperation (String) : References to a combination of the OpenAPI method & path (example: GET::/crm/leads)

• excludeForOperations (Array | optional) : References to OpenAPI operations that will be skipped for targeting, example: ["leadsAdd", "GET::/crm/leads/{id}"]

• tests (Array) : Array of additional Postman test scripts. Values can be the script content or path to the script file (with file: prefix).

• overwrite (Boolean true/false | Default: false) : Resets all generateTests and overwrites them with the defined tests from the tests array.
• append (Boolean true/false | Default: true) : Place the tests after (append) or before (prepend) all generated tests.

Portman - assignVariables properties

The "assignVariables" allows you to set Postman collection variables for easier automation.

assignVariables options

• openApiOperationId (String) : Reference to the OpenAPI operationId for which the Postman pm.collectionVariables will be set. (example: leadsAll)
• openApiOperationIds (Array) : References to an array of OpenAPI operationIds, for which the Postman pm.collectionVariables will be set. example: ['leadsAll', 'companiesAll', 'contactsAll']
• openApiOperation (String) : Reference to the combination of the OpenAPI method & path, for which the Postman pm.collectionVariables will be set. (example: GET::/crm/leads)

• excludeForOperations (Array | optional) : References to OpenAPI operations that will be skipped for targeting, example: ["leadsAdd", "GET::/crm/leads/{id}"]

• collectionVariables (Array) : Array of key/value pairs to set the Postman collection variables.

  • responseBodyProp (String) : The property for which the value will be taken from the response body and set the value as the pm.collectionVariables value. To store the root level, use . as key.
  • responseHeaderProp (String) : The property for which the value will be taken from the response header and set the value as the pm.collectionVariables value.
  • requestBodyProp (String) : The property for which the value will be taken from the request body and set the value as the pm.collectionVariables value.
  • value (String) : The defined value that will be set as the pm.collectionVariables value. The value can be generated using template expressions. For the full list of template expressions, check the Assign & Overwrite example
  • name (string OPTIONAL | Default: <operationId>.<varProp>) : The desired name that will be used to as the Postman variable name. If the name is not provided, Portman will generate a variable name, using the <operationId>.<varProp>. You can pass your own template expressions, to dynamically generate variable names. The template can contain the following dynamic expressions: <operationId> results in the OpenAPI operation ID (example leadsAdd), <path> results in the OpenAPI operation ID (example /crm/leads), <pathRef> results in the Portman operation (example POST::/crm/leads_POST), <method> results in the OpenAPI method (example GET), <opsRef> results in the OpenAPI operationId with a fallback to the pathRef in case the OpenAPI does not contain an operation ID. For the full list of dynamic expressions, check the Assign & Overwrite example.

For more details, review the Assign variables example and Assign & Overwrite example.

Portman - overwrites properties

To facilitate automation, you might want to modify properties with "randomized" or specific values. The overwrites are mapped based on the OpenAPI operationId or OpenAPI Operation reference.

overwrites options

• openApiOperationId (String) : Reference to the OpenAPI operationId for which the Postman request will be overwritten or extended. (example: leadsAll)
• openApiOperationIds (Array) : References to an array of OpenAPI operationIds, for which the Postman request will be overwritten or extended (example: ['leadsAll', 'companiesAll', 'contactsAll'])
• openApiOperation (String) : Reference to combination of the OpenAPI method & path, for which the Postman request will be overwritten or extended (example: GET::/crm/leads)

• excludeForOperations (Array | optional) : References to OpenAPI operations that will be skipped for targeting. (example: ["leadsAdd", "GET::/crm/leads/{id}"])

• overwriteRequestBaseUrl (Object) :

  Key/value pair to overwrite the Postman Request Base URL.

  • value (String) : The value that will be used to overwrite/extend the value in the request base URL. (example: https://example.com or {{baseUrl}}).
  • overwrite (Boolean true/false | Default: true) : Overwrites the request base URL value OR attach the value to the original request base URL value.
  • remove (Boolean true/false | Default: false) : Removes the targeted request base URL from Postman.

• overwriteRequestQueryParams (Array) :

  Array of key/value pairs to overwrite in the Postman Request Query params.

  • key (String) : The key that will be targeted in the request Query Param to overwrite/extend. Supports wildcard * to match any sequence of characters. For example, filter[*] matches filter[0], filter[1], etc.
  • value (String) : The value that will be used to overwrite/extend the value in the request Query Param OR use the Postman Dynamic variables to use dynamic values like {{$guid}} or {{$randomInt}}. Supports also templating to generate variable names. The template can contain the following dynamic expressions: <operationId> results in the OpenAPI operation ID (example leadsAdd), <path> results in the OpenAPI operation ID (example /crm/leads), <pathRef> results in the Portman operation (example POST::/crm/leads_POST), <method> results in the OpenAPI method (example GET), <opsRef> results in the OpenAPI operationId with a fallback to the pathRef in case the OpenAPI does not contain an operation ID. For the full list of dynamic expressions, check the Assign & Overwrite example.
  • overwrite (Boolean true/false | Default: true) : Overwrites the request query param value OR attach the value to the original request query param value.
  • disable (Boolean true/false | Default: false) : Disables the request query param in Postman.
  • remove (Boolean true/false | Default: false) : Removes the targeted request query param from Postman.
  • insert (Boolean true/false | Default: true) : Insert additional the request query param in Postman that are not present in OpenAPI.
  • description (String) : Overwrites the request query param description in Postman.

• overwriteRequestPathVariables (Array) :

  Array of key/value pairs to overwrite in the Postman Request Path Variables.

  • key (String) : The key that will be targeted in the request Path variables to overwrite/extend.
  • value (String) : The value that will be used to overwrite/extend the value in the request path variable OR use the Postman Dynamic variables to use dynamic values like {{$guid}} or {{$randomInt}}. Supports also templating to generate variable names. The template can contain the following dynamic expressions: <operationId> results in the OpenAPI operation ID (example leadsAdd), <path> results in the OpenAPI operation ID (example /crm/leads), <pathRef> results in the Portman operation (example POST::/crm/leads_POST), <method> results in the OpenAPI method (example GET), <opsRef> results in the OpenAPI operationId with a fallback to the pathRef in case the OpenAPI does not contain an operation ID. For the full list of dynamic expressions, check the Assign & Overwrite example.
  • overwrite (Boolean true/false | Default: true) : Overwrites the request path variable value OR attaches the value to the original request Path variable value.
  • remove (Boolean true/false | Default: false) : Removes the targeted request path variable from Postman.
  • insert (Boolean true/false | Default: true) : Insert additional the request path variable in Postman that are not present in OpenAPI.
  • description (String) : Optional, Overwrites the request path variable description in Postman.

• overwriteRequestHeaders (Array) :

  Array of key/value pairs to overwrite in the Postman Request Headers.

  • key (String) : The key that will be targeted in the request Headers to overwrite/extend.
  • value (String) : The value that will be used to overwrite/extend the value in the request headers OR use the Postman Dynamic variables to use dynamic values like {{$guid}} or {{$randomInt}}. Supports also templating to generate variable names. The template can contain the following dynamic expressions: <operationId> results in the OpenAPI operation ID (example leadsAdd), <path> results in the OpenAPI operation ID (example /crm/leads), <pathRef> results in the Portman operation (example POST::/crm/leads_POST), <method> results in the OpenAPI method (example GET), <opsRef> results in the OpenAPI operationId with a fallback to the pathRef in case the OpenAPI does not contain an operation ID. For the full list of dynamic expressions, check the Assign & Overwrite example.
  • overwrite (Boolean true/false | Default: true) : Overwrites the request header value OR attaches the value to the original request header value.
  • disable (Boolean true/false | Default: false) : Disables the request header in Postman.
  • remove (Boolean true/false | Default: false) : Removes the targeted request header from Postman.
  • insert (Boolean true/false | Default: true) : Insert the additional request header in Postman that are not present in OpenAPI.
  • description (String) : Overwrites the request header description in Postman.

• overwriteRequestBody (Array) :

  Array of key/value pairs to overwrite in the Postman Request Body.

  Applicable for request body types: JSON/form-data/x-www-form-urlencoded

  • key (String) : The key that will be targeted in the request body to overwrite/extend. Use the . notation to target nested properties. To target the root level, use . as key.
  • value (Any) : The value that will be used to overwrite/extend the key in the request body OR use the Postman Dynamic variables to use dynamic values like {{$guid}} or {{$randomInt}}. The value can be a text/number/boolean/array/object or Postman variable (to pass the Postman variable as type boolean or number, use {{{variableName}}} surrounded by 3x {{{ and 3x }}}). Supports also templating to generate variable names. The template can contain the following dynamic expressions: <operationId> results in the OpenAPI operation ID (example leadsAdd), <path> results in the OpenAPI operation ID (example /crm/leads), <pathRef> results in the Portman operation (example POST::/crm/leads_POST), <method> results in the OpenAPI method (example GET), <opsRef> results in the OpenAPI operationId with a fallback to the pathRef in case the OpenAPI does not contain an operation ID. For the full list of dynamic expressions, check the Assign & Overwrite example.
  • overwrite (Boolean true/false | Default: true) : Overwrites the request body value OR attaches the value to the original request body value.
  • remove (Boolean true/false | Default: false) : Removes the request body property, including the value.

  Applicable for request body types: form-data/x-www-form-urlencoded

  • insert (Boolean true/false | Default: true) : Insert the additional request form key/value in Postman that are not present in OpenAPI.
  • description (String) : Overwrites the request form data description in Postman.

• overwriteRequestSecurity (Object) :

  A Postman RequestAuthDefinition object that will be applied to the request.The security overwrites provides a number of security types:

  • remove (Boolean true/false | Default: false) : Unsets the Authorization type in Postman.

  • apiKey: The API key auth will send a key-value pair to the API either in the request headers or query parameters.

    • value (String) : The value that will be inserted as the Postman apiKey value. It can be a plain value or a Postman variable.
    • key (String | optional) : The "key" value that will be inserted in the Postman apiKey key field. It can be a plain value or a Postman variable.
    • in (String | optional) : The "in" value that defines where the Api Key will be added in the Postman request Header or Query params. Postman supports header for "Header" or query for "Query Params".

  "overwriteRequestSecurity": {
        "apiKey": {
          "value": "{{apiKey}}"
        }
      }

  • bearer: The bearer tokens allow requests to authenticate using an access key, such as a JSON Web Token (JWT).
    • token (String) : The "token" that will be inserted as the Postman bearer token value. It can be a plain value or a Postman variable.

  "overwriteRequestSecurity": {
        "bearer": {
          "token": "{{bearerToken}}"
        }
      }

  • basic: Basic authentication involves sending a verified username and password with your request.
    • username (String) : The username that will be inserted as the basic authentication username value
    • password (String) : The password that will be inserted as the basic authentication password value

  "overwriteRequestSecurity": {
        "basic": {
          "username": "{{username}}",
          "password": "{{password}}",
        }
      }

  • Postman security options: Overwrite/Insert Postman authorization settings.
    • Postman Type (Array) : The Postman authorization option type. Supported types are: awsv4, digest, edgegrid, ntlm, oauth1, oauth2
      • Attributes : key/value/type as defined in Postman (the easiest way to define it, is to set it manually in Postman, export the collection and extract the matching values from the JSON file).

For more details, review the Overwrites example and Assign & Overwrite example.

Portman - fuzzing properties - BETA 🏗

NOTICE: This feature is considered BETA, since we are investigating additional fuzzing capabilities.

Fuzzing or fuzz testing is an automated software testing technique that involves providing invalid, unexpected, or random data as inputs to a computer program (a REST API in the case of Portman).

Fuzzing changes the requests (body, query params, ... ) to unexpected values in an effort to cause unexpected behavior and errors in the API response. For Portman, we want to provide a simple form of Fuzzing, with the goal to trigger validation/error responses, which can be contract tested. The automatic fuzzing is based on the OpenAPI request properties, where for each fuzzing variation a new Postman request will be generated, with optional contract tests.

The Fuzzing options describe the configuration setting for available OpenAPI fuzzing variations.

REMARKS:

• Postman Dynamic variables are rendered before being fuzzed.
• Regular Postman variables are skipped from fuzzing.

fuzzing options

• requestBody (Array) :

  An array of fuzzing options for the Postman Request Body.

  REMARK: Fuzzing is only applicable for OpenAPI request bodies of media type: "application/json"

  • requiredFields (Boolean) : Removes the properties & values from the request body that are marked as "required" in OpenAPI.
  • minimumNumberFields (Boolean) : Changes the values of the numeric fields to a lower value than the defined "minimum" property in the OpenAPI document.
  • maximumNumberFields (Boolean) : Changes the value of the numeric fields to a higher value than the defined "maximum" property in the OpenAPI document.
  • minLengthFields (Boolean) : Changes the length of the value to a lower length than the defined "minLength" property in the OpenAPI document.
  • maxLengthFields (Boolean) : Changes the length of the value to a higher length than the defined "maxLength" property in the OpenAPI document.

• requestQueryParams (Array) :

  An array of fuzzing options for the Postman Request Query parameters.

  • requiredFields (Boolean) : Removes the properties & values from the request query params that are marked as "required" in OpenAPI.
  • minimumNumberFields (Boolean) : Changes the values of the numeric fields to a lower value than the defined "minimum" property in the OpenAPI document.
  • maximumNumberFields (Boolean) : Changes the value of the numeric fields to a higher value than the defined "maximum" property in the OpenAPI document.
  • minLengthFields (Boolean) : Changes the length of the value to a lower length than the defined "minLength" property in the OpenAPI document.
  • maxLengthFields (Boolean) : Changes the length of the value to a higher length than the defined "maxLength" property in the OpenAPI document.

• requestHeaders (Array) :

  An array of fuzzing options for the Postman Request Headers.

  • requiredFields (Boolean) : Removes the properties & values from the request headers that are marked as "required" in OpenAPI.
  • minimumNumberFields (Boolean) : Changes the values of the numeric fields to a lower value than the defined "minimum" property in the OpenAPI document.
  • maximumNumberFields (Boolean) : Changes the value of the numeric fields to a higher value than the defined "maximum" property in the OpenAPI document.
  • minLengthFields (Boolean) : Changes the length of the value to a lower length than the defined "minLength" property in the OpenAPI document.
  • maxLengthFields (Boolean) : Changes the length of the value to a higher length than the defined "maxLength" property in the OpenAPI document.

For more details, review the fuzzing example.

Portman - operationPreRequestScripts properties

The operationPreRequestScripts configuration will inject pre-request scripts in the Postman collection, on request level. Postman executes pre-request scripts before a request runs. If you want to set the Postman Collection pre-request scripts on the collection level, you can use the globals > collectionPreRequestScripts configuration. The operationPreRequestScripts is inserted on the request level.

operationPreRequestScripts options

• openApiOperationId (String) : Reference to the OpenAPI operationId on which the "Pre-request Scripts" will be inserted. (example: leadsAll)
• openApiOperationIds (Array) : References to an array of OpenAPI operationIds, for which the "Pre-request Scripts" will be inserted (example: ['leadsAll', 'companiesAll', 'contactsAll']
• openApiOperation (String) : Reference to combination of the OpenAPI method & path, for which the "Pre-request Scripts" will be inserted (example: GET::/crm/leads)

• excludeForOperations (Array | optional) : References to OpenAPI operations that will be skipped for targeting. (example: ["leadsAdd", "GET::/crm/leads/{id}"])

• scripts (Array) : Array of scripts that will be injected as Postman Pre-request Scripts on request level, that will be executed before the targeted requests in this collection. Values can be the script content or path to the script file (with file: prefix).

Portman - globals property

The configuration defined in the globals will be executed on the full Postman collection. This is handy if you need to do mass replacements of variables or specific words/keys/values in the full collection that cannot be overwritten per request.

globals options

• stripResponseExamples (Default: false) : Strip the response examples from the generated Postman collection.
• variableCasing : Change the casing of the auto-generated Postman variables. Supported values are: camelCase, pascalCase, kebabCase, trainCase, snakeCase, adaCase, constantCase, cobolCase, dotNotation. See the Assign & Overwrite example for the different casing options.
• separatorSymbol (Default: "::") : Change the separator symbol for the auto-generated Postman testName description (Example: [GET]::/crm/leads - Status code is 2xx). Helpful when using the postman-to-k6 converter.
• collectionPreRequestScripts : Array of scripts that will be injected as Postman Collection Pre-request Scripts that will be executed by Postman before every request in this collection. Values can be the script content or path to the script file (with file: prefix).
• collectionTestScripts: Array of scripts that will be injected as Postman Collection Test Scripts will be executed by Postman after every request in this collection. Values can be the script content or path to the script file (with file: prefix).
• collectionVariables: A map of key value pairs that will inserted as Postman collection variables.
• keyValueReplacements : A map of parameter key names that will have their values replaced with the provided Postman variables.
• valueReplacements : A map of values that will have their values replaced with the provided values.
• rawReplacements : Consider this a "search & replace" utility, that will search a string/object/... and replace it with another string/object/... This is very useful to replace data from the OpenAPI specification, before it is used in the Portman test automation generation.
• portmanReplacements : The "search & replace" utility right before the final Postman file is written, that will search a string/object/... and replace it with another string/object/... This is practical to replace any data from the generated Portman collection, before it is used in Postman / Newman test execution.
• orderOfOperations : The orderOfOperations is a list of OpenAPI operations, which is used by Portman to sort the Postman requests in the desired order, in their folder. The ordering from orderOfOperations is performed per folder. Items that are not defined in the orderOfOperations list will remain at their current order.
• orderOfFolders : The orderOfFolders is a list of Postman folder names, which is used by Portman to sort the Postman folders in the desired order. Folders that are not defined in the orderOfFolders list will remain at their current order, after the re-order folders.

• securityOverwrites : Overwrite of the OpenAPI Security Scheme Object (supported types: "apiKey", "http basic auth", "http bearer token") or inject a Postman authorization option (supported types: awsv4, digest, edgegrid, ntlm, oauth1, oauth2) on a collection level.

  The security overwrites provides a number of security types:

  • remove (Boolean true/false | Default: false) : Unsets the Authorization type in Postman.

  • apiKey: The API key auth will send a key-value pair to the API either in the request headers or query parameters.

    • value (String) : The value that will be inserted as the Postman apiKey value. It can be a plain value or a Postman variable.
    • key (String | optional) : The "key" value that will be inserted in the Postman apiKey key field. It can be a plain value or a Postman variable.
    • in (String | optional) : The "in" value that defines where the Api Key will be added in the Postman request Header or Query params. Postman supports header for "Header" or query for "Query Params".

  "securityOverwrites": {
        "apiKey": {
          "value": "{{apiKey}}"
        }
      }

  • bearer: The bearer tokens allow requests to authenticate using an access key, such as a JSON Web Token (JWT).
    • token (String) : The "token" that will be inserted as the Postman bearer token value. It can be a plain value or a Postman variable.

  "securityOverwrites": {
        "bearer": {
          "token": "{{bearerToken}}"
        }
      }

  • basic: Basic authentication involves sending a verified username and password with your request.
    • username (String) : The username that will be inserted as the basic authentication username value
    • password (String) : The password that will be inserted as the basic authentication password value

  "securityOverwrites": {
        "basic": {
          "username": "{{username}}",
          "password": "{{password}}",
        }
      }

  • Postman security options: Overwrite/Insert Postman authorization settings.
    • Postman Type (Array) : The Postman authorization option type. Supported types are: awsv4, digest, edgegrid, ntlm, oauth1, oauth2
      • Attributes : key/value/type as defined in Postman (the easiest way to define it, is to set it manually in Postman, export the collection and extract the matching values from the JSON file).

  {
    "globals": {
      "securityOverwrites": {
        "oauth1": [
          {
            "key": "addEmptyParamsToSign",
            "value": true,
            "type": "boolean"
          },
          {
            "key": "timestamp",
            "value": "1461319769",
            "type": "string"
          },
          {
            "key": "nonce",
            "value": "ik3oT5",
            "type": "string"
          },
          {
            "key": "consumerSecret",
            "value": "D+EdQ-gs$-%@2Nu7",
            "type": "string"
          },
          {
            "key": "consumerKey",
            "value": "RKCGzna7bv9YD57c",
            "type": "string"
          },
          {
            "key": "signatureMethod",
            "value": "HMAC-SHA1",
            "type": "string"
          },
          {
            "key": "version",
            "value": "1.0",
            "type": "string"
          },
          {
            "key": "addParamsToHeader",
            "value": false,
            "type": "boolean"
          }
        ]
      }
    }
  }

For more details on the globals configuration options , review the globals example and ordering example

Configure automatic upload to Postman App

REMARK: Portman does not require you to have a Postman account.

In case you want to sync the generated Postman collection with the Postman app (portman --syncPostman), you would need a Postman account since Portman leverages the Postman API to sync the collection.

This can be a "free" Postman account or any of the paid Postman plans.

The generated Postman collection can always be imported manually, without a Postman account.

To enable automatic uploads of the generated Postman collection through Portman, follow these steps:

1. Get your Postman API key

1. Goto the root folder of your project

2. Copy env-postman-app-example as .env in the root folder of your project

3. Enter your Postman API key in a local .env file, as POSTMAN_API_KEY=[replace with Postman api key]

Next to the Postman API key, you can also pass along the Postman Workspace name & the specific Postman Collection UID.

Supported Postman API .ENV variables:

• POSTMAN_API_KEY : Postman API key
• POSTMAN_WORKSPACE_NAME : Postman Workspace name to target the upload of the generated Postman collection
• POSTMAN_COLLECTION_UID : Postman collection UID to upload with the generated Postman collection

The POSTMAN_WORKSPACE_NAME & POSTMAN_COLLECTION_UID variables can also be set as CLI Options --postmanWorkspaceName & --postmanUid , which will overrule the variables defined in the .ENV file.

RECOMMENDATION: Do not commit the .env file in any versioning system like GIT if it contains confidential credentials.

Credits

Portman started as a PR on the handy openapi-to-postman package to generate basic Postman tests from the OpenAPI specification.

Apideck immediately saw the PR's value and collaborated with the original author, Tim Haselaars, to adopt the functionality and extend the options & tooling to create "Portman".

The goal of Portman is to drive API automation by 'porting' a static OpenAPI document to a dynamic Postman collection that includes a powerful testing suite with variable requests, bodies and more. All this while being easy to configure & ready to use.

Portman is a valuable tool in any OpenAPI workflow, for local development or as part of a CI/CD automation pipeline.

Credits for this package for the hard work of Nick Lloyd and Tim Haselaars.

Future ideas

• <input disabled="" type="checkbox"> Make Postman security dynamic

Resources

A collection of blog posts and resources about Portman

• https://www.andmore.dev/blog/getting-started-portman/ by andmoredev
• https://itnext.io/automating-api-testing-with-portman-postman-and-newman-ec1a869cbc99 by Tyler Owen
• https://www.codecentric.de/wissens-hub/blog/charge-your-apis-volume-3-optimizing-api-testing-with-contract-testing by Daniel Kocot
• https://blog.apideck.com/portman-api-testing by Chris Wood
• https://dev.to/oneadvanced/api-provider-contract-testing-for-all-with-portman-openapi-and-postman-4ll1 by Alex Savage
• https://github.com/thim81/spec-driven-openapi-contract-performance-testing by Tim Haselaars
• https://www.codecentric.de/wissens-hub/blog/charge-your-apis-volume-25-contract-testing by Pasquale Brunelli
• https://qase.io/blog/automated-contract-testing/amp/ Contract Testing in Action by Kirill Ivliev

[Unreleased]

v1.33.0 - (2025-09-12)

• CLI - Exits with code 1 when Portman config validation fails (#705)
• Newman Return process exit code when option is abortOnFailure (#504)
• Bumped dependencies

v1.32.1 - (2025-07-10)

• Fuzzing - only map required fields if required property is an array (#702)
• Contract testing - Handle default response code (#431)
• Variation testing - Handle default response code (#431)
• Variations - Support wildcard for response codes

v1.32.0 - (2025-07-09)

• Variations - Set content-type for response
• Variations - Set content-type for request body
• Contract testing - Set content-type for request body
• Contract testing - Set content-type for response
• Added examples for variation & contract testing with multiple content-types
• Overwrites - Added support for overwriting file form-data values
• Bumped dependencies openapi-format 1.27.1

v1.31.1 - (2025-04-03)

• Removed Clearbit references (#693)
• Bumped dependencies openapi-format 1.25.2

v1.31.0 - (2025-03-29)

• Bumped openapi-to-postman to 5.0.0

v1.30.8 - (2025-03-29)

• Generate safe variable names in the Postman scripts (#687)
• CLI - Warn about unsupported flags (#686)
• Bumped dependencies: openapi-format 1.25.1

v1.30.7 - (2024-11-05)

• matchPath - Improved matching with ending wildcard (#674)

v1.30.6 - (2024-11-01)

• matchPath - Further improved path matching (#672)

v1.30.5 - (2024-11-01)

• Apply casing to auth variable (#668)
• Improved path matching (#669)
• Improved documentation(#671)
• Warn for missing targets (#632 #391)

v1.30.4 - (2024-10-07)

• Handle Postman API non-200 responses better (#660)
• Handle scalar $ref: >- (#661)

v1.30.3 - (2024-09-27)

• Improved loading split local OpenAPI files
• Bumped dependencies: openapi-format 1.24.0

v1.30.2 - (2024-09-11)

• testResponseBodyContent - prevent PM variables as string (#650)
• testResponseHeaderContent - support using PM variables in oneOf check
• overwrite - handle overwrite of non-empty objects with plain values (#646)
• Bumped dependencies: openapi-format 1.23.0

v1.30.1 - (2024-08-27)

• Improved OpenAPI to JSON schema conversion to handle OpenAPI-specific properties (#642 #494)
• Strip unneeded OpenAPI-specific properties ('discriminator', 'readOnly', 'writeOnly', 'xml', 'externalDocs', 'example','deprecated') for more compact JSON schemas.
• Added JSON schema validation warning during conversion, to inform the users. (#644)
• Fix for unwanted minItems, maxItems addition in the JSON schema
• overwriteRequestQueryParams - Remove form encoded array query params ((#640))
• overwriteRequestQueryParams - Insert additional form encoded array query params (#640)
• Bumped dependencies: newman

v1.30.0 - (2024-08-23)

• Portman - sort Postman folders based on the "orderOfFolders" configuration (#621)
• overwriteRequestQueryParams - Handle form encoded array query params (#640)

v1.29.3 - (2024-08-19)

• Portman - Make OpenAPI data immutable (#630)
• Bumped dependency openapi-format
• Removed unused yaml package

v1.29.2 - (2024-08-19)

• Skip read-only properties from request body (#628)
• YAML error fix using latest openapi-format (#631)
• Bumped dependencies: openapi-to-postman 4.24.0, newman, openapi-format

v1.29.1 - (2024-08-08)

• Fuzzing - Handle nested plain array values (#629)

v1.29.0 - (2024-08-06)

[!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.

• Conversion - Use convertV2 from openapi-to-postman
• overwriteRequestSecurity - handle missing auth (#622)
• Fuzzing - Fix nested path handling (#624)
• Globals - Strip response example from root requests

v1.28.0 - (2024-07-22)

• overwriteRequestQueryParams - Added wildcard matching for query param keys (#612)
• OpenAPI conversion - Use the first-listed content-type as request body (#601)
• overwriteRequestSecurity - Improved logic to handle OAuth2
• overwriteRequestHeaders - Fix missing request auth (#600)
• assignVarFromValue - Add template expressions as value (#595)
• Template expression: Fix to handle double/triple curly braces (#597)
• overwriteRequestHeaders - Allow zero value
• overwriteRequestPathVariables - Allow zero value
• overwriteRequestQueryParams - Allow zero value (#603)
• Fuzzing - Improve fuzzing with zero values (#599)
• Improved OpenAPI parsing error reporting (#591)
• Dependencies - Replaced faker with @faker-js (#593)
• Updated overwrite examples and added preRequestScripts example by @jpjpjp (#598)
• Bumped dependencies: openapi-to-postman 4.23.0, replaced traverse with neotraverse, removed camelCase

v1.27.0 - (2024-06-16)

• overwrites - Added the removal of Authorization using overwriteRequestHeaders,overwriteRequestSecurity, securityOverwrites (#580)
• Improved OpenAPI version to Postman version conversion (#578)
• Updated readme & examples by @jpjpjp
• Bumped dependencies

v1.26.6 - (2024-06-05)

• Add OpenAPI version conversion to Postman Collection version (handy for usage in Microcks) (#577)
• Bumped dependencies: openapi-to-postman 4.21.0

v1.26.5 - (2024-03-08)

• headersPresent: Add check only for required headers (#566)

v1.26.4 - (2024-03-06)

• Bugfix to support http & https remote files (#562)

v1.26.3 - (2024-02-07)

• overwriteRequestQueryParams - Auto-enable query parameters when overwrite value is set (#559)
• overwriteRequestHeaders - Auto-enable headers when overwrite value is set (#559)
• normalizedPathRef: Improve handling colon character (#556)

v1.26.2 - (2024-01-28)

• Fuzzing - Enable query parameters and headers for fuzzed values (#554)

v1.26.1 - (2024-01-18)

• overwriteRequestHeaders: Added disable false option (#551)
• Bumped dependencies: openapi-to-postman 4.19.0 (#551)

v1.26.0 - (2024-01-16)

• Portman - Change default enableOptionalParameters setting to false (#550)

[!CAUTION]
Breaking Change: The default behaviour of the Query parameters is changed since version 1.26.0.
Optional query parameters will be disabled in Postman by default.

This will reduce the need for extra Portman config to disable the optional query parameters in the Postman collection and provide a more expected result in Postman.

OpenAPI:

    limitParam:
      name: limit
      in: query
      description: (Required) Number of records to return
      required: true # <----------
      schema:
        type: string

BEFORE

All the query parameters are enabled in the Postman collection.

AFTER

Only the required query parameters are enabled in the Postman collection.

You can modify this default behaviour by using --postmanConfigFile parameters. This will allow you to provide a specific configuration file that will be used for converting the OpenAPI specification to Postman.

See postmanConfigFile example for more info.

v1.25.1 - (2024-01-16)

• AssignVariables: Fix casing for template expressions for variable props (#549)

v1.25.0 - (2024-01-15)

• AssignVariables: Option to use template expressions for variable names (#548)
• AssignVariables: Option to use template expressions for variable properties for Request body, Response body & header (#548)
• Overwrites: Option to use template expressions for values (#548)
• Globals: Define the casing of the generated variable names (#541)
• Globals: Apply variableCasing for injected .ENV variables (#548)
• Globals: Define the separatorSymbol used in the Postman test names (#541)
• Support for loading local or remote JSON/YAML config files (#547)
• Implement openapi-format as module (#539)
• Fix includeTests parameter behaviour (#544)
• Updated examples

v1.24.0 - (2024-01-05)

• Globals - Added the option set 'collectionVariables' for setting variables on collection level

v1.23.2 - (2024-01-05)

• Added $schema to the Portman JSON Schema for auto-completion
• Bumped dependencies: openapi-to-postmanv2 4.18.0, newman 6.1.0, postman-collection 4.3.0, openapi-format 1.15.2, axios 1.6.4

v1.23.1 - (2023-10-28)

• overwriteRequestSecurity - Handle missing auth config (#509)
• overwriteRequestQueryParams - Enable disabled query params (#484)

v1.23.0 - (2023-10-28)

• orderOfOperations - Adjusted ordering string matching to be exact when wildcard is not present (#490)
• ContentTests - Add pm variable support for oneOf assertions in content tests (#520)
• Postman Sync - Set no limit to the body size on collection update (#517)
• Postman Sync - Removes extra query params from url for the file name (#525)
• Fuzzing - Exclude properties with reserved names from fuzzing (#514)
• Bugfix for overwriteRequestBody - should root overwrite (#524)
• Bumped dependencies

v1.22.0 - (2023-03-26)

• syncPostmanCollectionIds - Synchronises the IDs of newly created postman collections (#457)
• securityOverwrites - Set auth settings when no auth is defined (#472)
• overwriteRequestSecurity - Keep API key when no key is provided (#468)
• orderOfOperations - Prevent error (#467)

v1.21.0 - (2023-02-27)

• Bumped openapi-to-postman to 4.9.0 which support OpenAPI 3.1
• Bugfix for integrationTests - merge folders/suites into one (#361)
• Bugfix to overwrite request headers with empty values (#459)
• Bugfix for overwriteRequestBaseUrl - overwrite value with path parameters excludes parameters (#446)
• Bugfix for handling Postman variables in the path when targeting (#445)
• Bugfix for handling null values safer for analyzeFuzzJsonSchema (#443)
• Bugfix for handling variable injection of the baseUrl & server variables (#408, #437)
• Bumped dependencies

v1.20.1 - (2022-12-06)

• Bugfix "overwriteRequestBaseUrl" to keep the path parameters (#434)

v1.20.0 - (2022-12-06)

• AssignVariables - Added support to assign the root of the request body as variable (#429)
• Overwrites - added "overwriteRequestBaseUrl" to overwrite the request base url
• Bumped dependencies

v1.19.0 - (2022-11-06)

• overwriteRequestBody - added support for type "form-data" (#325)
• overwriteRequestBody - added support for type "x-www-form-urlencoded" (#325)
• AssignVariables - Added support for null values for response body (#414)
• ContentTests - Added support for null values for response body (#414)
• ContentTests - Added support to look up a key within an array of objects by using a * wildcard (#417)
• Documentation - Updated the ordering example (#418,#423)
• Added Portman as Docker (#260)

v1.18.1 - (2022-09-30)

• Fix unwanted schema validation (#392)
• Fix Newman option not properly formatted (#395)
• Bumped dependencies

v1.18.0 - (2022-07-19)

• Overwrites - Automatically convert values for request query parameters, path variables & headers to string (#336, #384)
• Fix ContentTests with length/minLength/maxLength checks with 0 (zero) as value (#369)
• Fix ContentTests with empty as value
• ContentTests - Added "notExist" check for response body & headers (#364)
• ContentTests - Added "assert" option for response body & headers (#372)
• ContentTests - Added support for special characters in request body property names (#365)
• AssignVariables - Added support for special characters in request body property names (#365)
• Postman Sync - Fix for issue where POSTMAN_COLLECTION_UID was ignored (#353)
• Postman Sync - Improved the Portman API output for API error. (#367)
• overwriteRequestPathVariables - Support empty as value (#382)
• overwriteRequestPathVariables - Added the option to insert new path variables in Postman
• overwriteRequestPathVariables - Added the option to remove path variables in Postman
• Bumped dependencies

v1.17.0 - (2022-06-21)

• Fix missing integrationTests when using "bundleContractTests" (#330)
• ContentTests - allow targeting of root object or array (#334)
• Tests - support bracket notation for targeted keys (#333)
• Fuzzing - support JSON variants as content-type (#332)
• Fuzzing - added support for allOf, anyOf, oneOf schemas (#335)
• Fuzzing - added min/maxLength support for arrays (#335)
• ContentTest - Added "oneOf" check for response body & header (#313)
• Bumped dependencies openapi-format, jest, @apideck/better-ajv-errors, @apidevtools/swagger-parser, fs-extra

v1.16.1 - (2022-04-13)

• Set the 'logAssignVariables' option via 'cliOptions' to toggle console output for assigned variables

v1.16.0 - (2022-04-13)

• Bumped dependency versions of ajv, yargs, fp-ts
• Added the 'logAssignVariables' CLI option to toggle console output for assigned variables (#317)
• Globals - Added the option set 'collectionTestScripts' for Test Scripts on collection level (#305)
• Globals - Overwrite OpenAPI authorization with the 'securityOverwrites' (#306)

v1.15.1 - (2022-04-01)

• ExtendTest - Allow importing files for extendTest (#304)
• Extended supported OpenAPI methods (#306)
• Fix for incorrect en/decoding of boolean/number Postman variables (#286)
• Enhance generated schema validation to support double as a format (#307)

v1.15.0 - (2022-03-28)

• Bumped dependency versions of axios, ajv, @apideck/better-ajv-errors, Newman, and openapi-format
• Enhance generated schema validation to support float as a format (#281)
• Fix handling of the Global configuration properties (#261)
• Improved file handling, including support for directory creation (#278)
• Support $ref for Portman config (#277)
• Set Postman variables as boolean & number types in overwriteRequestBody (#295)
• securityOverwrites - Added support for Postman authorization options (#272)

v1.14.2 - (2022-02-22)

• Fuzzing - skip nullable required properties
• Bumped dependency follow-redirects

v1.14.1 - (2022-02-10)

• Bumped dependencies openapi-format to 1.9.2

v1.14.0 - (2022-02-09)

• Allow importing files for operationPreRequestScripts and collectionPreRequestScripts
• Contract test - extended "jsonBody" to verify that a 204 response has no response body content
• Bumped dependencies openapi-format to 1.9.1
• Bumped dependencies openapi-to-postman to 2.14.1

REMARK: openapi-to-postman v2.14.1 introduces the change that the "Accept" header is now set based on the response content-type by default. For more info visit the Github PR. Additionally disableBodyPruning, a Postman specific property is added to the generated request object.

v1.13.1 - (2022-01-17)

• Extended orderOfOperations to include the sorting on root level, next to the folder sorting (#236)
• Fix for status code in contract test (#238)
• Patch for follow-redirects vulnerability
• Bumped dependencies

v1.13.0 - (2021-12-15)

• Contract test - extend JSON schema validation with option to set additional properties behaviour.
• ContentTest - Check length of array or string
• ContentTest - Check minimum length of array or string of response body
• ContentTest - Check maximum length of array or string of response body
• ContentTest - Check minimum length of array or string of response header
• ContentTest - Check maximum length of array or string of response header
• Fix for orderOfOperations for operations have multiple path variables (#208)
• Implemented suggested fix for orderOfOperations with * wildcard (#122)
• Updated dependencies

v1.12.2 - (2021-12-15)

• Added better handling of Postman API errors

v1.12.1 - (2021-12-03)

• Fuzzing - added support for deeply nested required properties in the request body
• Bugfix for unwanted removal of operations without OperationId when using "excludeForOperations" (#185)
• Bumped openapi-format to version 1.7.0

v1.12.0 - (2021-12-01)

• Added --ignoreCircularRefs option to allow OAS specs that contain invalid circular references to still be processed by Portman
• Added the --collectionName option to change the OpenAPI title & Postman collection name
• Added --stripResponseExamples CLI option to slim down generated Postman collection
• Fuzzing - added support for root array structure in the request body
• Update package dependencies

v1.11.0 - (2021-11-30)

• Improved caching of Postman API, reducing API calls towards Postman
• Added "postmanFastSync" option to sync collections faster by using delete & create of a new collection (new UID), instead of an update
• Added "postmanRefreshCache" Postman sync option to refresh all local cached Postman API data
• Added Fuzzing support for deeply nested properties

v1.10.2 - (2021-11-29)

• Support Node 12 (#175)

v1.10.1 - (2021-11-22)

• Fixed missing collection name issue (#171)
• Improved formatting of variation test example config (#170)

v1.10.0 - (2021-11-15)

• Overwrites - Extended the overwriteRequestHeaders capabilities with the option to insert new headers in Postman
• Overwrites - Extended the overwriteRequestQueryParams capabilities with the option to insert new query params in Postman
• ContentTest - Added new test type "requestHeader"
• ContentTest - Extended the ContentTest for "requestBody" with checks : contains, length
• ContentTest - Added the ContentTest for "requestHeader" with checks : key, value, contains, length
• Variation Testing - Added the option to target the expected openApiResponse, skipping the variation if the response is not defined in OpenAPI
• Added support for loading cliOptionsFile in YAML format
• Fix for bundle contract folder issue (#145)
• Rework PostmanSyncService to be more resilient when handling cross workspace workflows (#164)
• Extend unit tests for Postman class itself
• Update Portman Config jsonSchema
• Fix typo in OAS URL error string (#168)
• Fuzzing - Added fuzzing variation generation of the request body fields for OpenAPI properties: required, minimum number, maximum number, minLength, maxLength
• Fuzzing - Added fuzzing variation generation of the request query parameters for OpenAPI properties: required, minimum number, maximum number, minLength, maxLength
• Fuzzing - Added fuzzing variation generation of the request headers for OpenAPI properties: required, minimum number, maximum number, minLength, maxLength
• Fuzzing - Added support for Postman Dynamic Variables on the minLength, maxLength for fuzzing options

v1.9.3 - (2021-10-20)

• Improved the handling of JSON schema maxItems/minItems for the types: array or null
• Bumped dependencies

v1.9.2 - (2021-10-12)

• Added support for passing postmanWorkspaceName & postmanUid as .ENV variables
• Improved the "raw replacements" method to handle the special characters safely
• Bumped dependencies

v1.9.1 - (2021-10-04)

• Support loading Portman config in YAML format
• Added newmanOptionsFile as a Portman CLI option, to pass options for configuring Newman
• Bumped dependencies

v1.9.0 - (2021-09-30)

• Due to a quirk, 1.9.0 was a ghost. All changes are released in 1.9.1.

v1.8.3 - (2021-09-27)

• Support overwrites for a request body array and array related cases (#143)
• Implemented optional chaining for safer handling of JSON response when assigning vars
• Added an INFO message when variable could not be assigned

v1.8.2 - (2021-09-17)

• Code rebuild of missing fix for unwanted maxItems (#133)
• Handle array for assign responseBodyProp (#134)
• Documented "operationPreRequestScripts" properties in the readme

v1.8.1 - (2021-09-02)

• Bug fix for unwanted maxItems on the root level on a JSON Schema validation (#133)

v1.8.0 - (2021-08-26)

• Added support for Postman Workspace when uploading collections (#118)
• Bug fix where portmanReplacements & upload to Postman had different results (#130)
• Improve output for CI and smaller terminals (#126)
• Updated example

v1.7.0 - (2021-08-02)

Enhancement

• Added overwrite overwriteRequestSecurity to be able to fine tune auth on a request level. This allows you to (for example) ensure all operations are authenticated via variation tests.

v1.6.2 - (2021-08-02)

Housekeeping

• remove console.log from variable injection

v1.6.1 - (2021-07-30)

• Environment variables prefixed with PORTMAN_ will be added to the Collection variables. This allows CI/CD to handle dynamic injection of values that should not be commited to repo.

Enhancement

v1.6.0 - (2021-07-28)

Enhancement

• Added optional bundleContractTests to PortmanOptions that will take all operations that have contract tests applied, and move them to a 'Contract Test' folder on the root of the generated Collection
• Any operations that do not have any contract tests will remain in their original place on the Collection

v1.5.2 - (2021-07-27)

Bugfix

• Fix for proper handling of contract tests with "enabled:false" during tests generation (#115).

v1.5.1 - (2021-07-26)

Bugfix

• Replaced instances where we were spreading arrays until we can safely upgrade packages that rely on outdated tslib

v1.5.0 - (2021-07-23)

Enhancement

• Added SecurityOverwrite options for methods: apiKey, Bearer Token & basic auth (#106)

Bugfix

• Fix for the issue "spreadArray is not a function" since the __spreadArrays function for TypeScript has been deprecated (#99)

v1.4.4 - (2021-07-22)

Enhancement

• Updated docs with an example for filtering
• Bumped openapi-format to 1.2.5
• Fix to prevent the unwanted addition 'Variation Tests'

v1.4.3 - (2021-07-22)

Bugfix

• Fix conflicting prompt alias that would not allow --local to be passed in as cli argument

v1.4.2 - (2021-07-20)

Enhancement

• Optimised the upload to postman process (#41)

Bugfix

• Fix to handle invalid postmanUid impacting the upload to Postman (#88)

v1.4.1 - (2021-07-19)

Enhancement

• Portman exit codes have been changed to exit(1) to make it easier for external processes running Portman to distinguish fail vs. done.

v1.4.0 - (2021-07-16)

Enhancement

• Phased out "node-fetch" in favour of "Axios" + improved error handling for remote OAS files
• newmanRunOptions can now be passed as an object via cli argument --newmanRunOptions, or cliOptionsFile. This will be used to extend/overwrite Portmans default Newman options. 🎉

v1.3.3 - (2021-07-14)

Temporary fix

• Temporary fix for handling multiple content-types, where the contract will be based on the 1st content-type that is defined in the OpenAPI response.

v1.3.2 - (2021-07-09)

Globals

• Added option to define portmanReplacements for handling search & replace values after the Portman injection.

Bug Fix

• Fix to handle remote sources ending with a trailing /

v1.3.1 - (2021-07-09)

Config Validation

• use draft06 for schema validation

v1.3.0 - (2021-07-09)

Portman Config

• Use AJV and @apideck-libraries/better-ajv-errors to validate your Portman Config file on run

v1.2.2 - (2021-07-09)

Bug Fix

• Typo correction in readme
• Remove empty orderOfOperations from default config

v1.2.1 - (2021-06-30)

Housekeeping

• remove console log that snuck in where it shouldn't be

v1.2.0 - (2021-06-30)

Feature Release

Integration Tests

• Added ability to create Integration Tests within postman collection by ordering operations and tests specific to api implementation

PreRequest Scripts

• Added ability to configure PreRequest Scripts on an operation level

v1.1.3 - (2021-07-02)

Bug Fix

• global overrides now happen as soon as spec is converted to Postman collection to avoid infighting amount overwrites and injections

v1.1.2 - (2021-07-01)

Variation Tests

• Optimize overwrites for variations

v1.1.1 - (2021-06-30)

Variation Tests

• Fix to ensure overwrites for variations are not overwritten when running globals

CLI

• Fix incomplete Postman collection when using --localPostman CLI options

v1.1.0 - (2021-06-30)

Operation Selectors

• new openApiOperationsIds setting can be passed as an array to selector operations for Portman to act on.

CLI

• Added the option to upload a generated local postman collection and skip the Portman conversion

v1.0.6 - (2021-06-30)

CLI

• Added the option to load an existing postman collection and skip the openAPI to postman conversion

v1.0.5 - (2021-06-29)

Dependencies

• Added prompts package

v1.0.4 - (2021-06-29)

Dependencies

• move dev dependencies in package.json

v1.0.3 - (2021-06-29)

Dependencies

• updated postman-collection and others

v1.0.2 - (2021-06-21)

Bug Fixes

• contentTests that check against variables should use collectionVariables instead of environment variables

Variation Tests

• nested folders (including variation tests) will be ignored when performing orderOfOperations
• Added statusCode tests for variations based on the openApiResponse property

v1.0.1 - (2021-06-18)

Overwrites

• extend overwrites to allow injection of objects and not just primitive values

v1.0.0 - (2021-06-18)

First Release

• Major overhaul from base release
• All features listed below

Added:

• <input checked="" disabled="" type="checkbox"> Convert an OpenAPI document to a Postman collection
  • <input checked="" disabled="" type="checkbox"> Support for OpenAPI 3.0
• Extend the Postman collection with capabilities
  • <input checked="" disabled="" type="checkbox"> Assign collection variables
    • <input checked="" disabled="" type="checkbox"> from ENV file
    • <input checked="" disabled="" type="checkbox"> from response body properties
    • <input checked="" disabled="" type="checkbox"> from response header properties
    • <input checked="" disabled="" type="checkbox"> from request body properties
  • <input checked="" disabled="" type="checkbox"> Inject Postman contract tests with
    • <input checked="" disabled="" type="checkbox"> HTTP response code validation
    • <input checked="" disabled="" type="checkbox"> Response time validation
    • <input checked="" disabled="" type="checkbox"> Response content-type validation
    • <input checked="" disabled="" type="checkbox"> Response JSON body validation
    • <input checked="" disabled="" type="checkbox"> Response JSON schema validation
    • <input checked="" disabled="" type="checkbox"> Response content validation
    • <input checked="" disabled="" type="checkbox"> Custom Postman tests
  • <input checked="" disabled="" type="checkbox"> Inject Postman variation tests for
    • <input checked="" disabled="" type="checkbox"> HTTP response code validation
    • <input checked="" disabled="" type="checkbox"> Response time validation
    • <input checked="" disabled="" type="checkbox"> Response content-type validation
    • <input checked="" disabled="" type="checkbox"> Response JSON body validation
    • <input checked="" disabled="" type="checkbox"> Response JSON schema validation
    • <input checked="" disabled="" type="checkbox"> Response content validation
    • <input checked="" disabled="" type="checkbox"> Custom Postman tests
  • <input checked="" disabled="" type="checkbox"> Inject Postman with
    • <input checked="" disabled="" type="checkbox"> Pre-request scripts on a collection level
  • <input checked="" disabled="" type="checkbox"> Modify Postman requests by
    • <input checked="" disabled="" type="checkbox"> Overwriting request path variables
    • <input checked="" disabled="" type="checkbox"> Overwriting request query params
    • <input checked="" disabled="" type="checkbox"> Overwriting request headers
    • <input checked="" disabled="" type="checkbox"> Overwriting request body
    • <input checked="" disabled="" type="checkbox"> Replace keywords with custom defined keys
    • <input checked="" disabled="" type="checkbox"> Replace values with custom defined values
    • <input checked="" disabled="" type="checkbox"> Search & replace any key/value with a specific value
    • <input checked="" disabled="" type="checkbox"> Order the collections requests
• <input checked="" disabled="" type="checkbox"> Upload the Postman collection to your Postman app
• <input checked="" disabled="" type="checkbox"> Test the Postman collection through Newman
• <input checked="" disabled="" type="checkbox"> Manage everything in config file for easy local or CI/CD usage

v0.1.0 - (2021-05-31)

OpenApi-Format / CLI options

• Added CLI Option filterFile to pass path to filter options for ignoring requests in spec before passing to Postman conversion

v0.0.9 - (2021-05-28)

CLI options

• Added CLI Option envFile to pass a path to .env that Portman should use for variable injection

v0.0.8 - (2021-05-28)

Newman

• Set Newman option to ignore redirects

v0.0.7 - (2021-05-25)

OpenApi-to-postman

• Corrected the incorrect "checkRequestBody" variable definition to "checkResponseBody"
• Let testsuite overwriteRequests handle the disabling of params

v0.0.6 - (2021-05-25)

CLI options

• Resolve issue with overriding paths to defaults when not provided
• Extended hardcoded list of params to disable until they are passed in as config

v0.0.5 - (2021-05-25)

OpenApi-to-postman

• Bumped openapi-to-postman to the latest version, which includes extended assignPmVariables test capabilities
• Added examples for the test suite assignPmVariables function
• Added examples for the test suite overwriteRequests function

v0.0.4 - (2021-05-18)

OpenApi-to-postman

• Bumped openapi-to-postman to version 2.7.0, which includes ContentCheck test capabilities
• Added examples for the test suite generation
• Added examples for the test suite contentChecks function
• Made the "orderOfOperations" property optional

CLI options

• Adds the CLI option to configure the Portman CLI in a JSON file
• Adds the CLI option to configure output location of the Postman file
• Adds the CLI option to toggle upload to Postman

Portman enhancements

• Adds the Portman option to sort Postman requests based on the "orderOfOperations" configuration
• Extends the Postman integration to upsert a collection based on the collection name

v0.0.3 - (2021-05-06)

• Adds CLI options to pass in path to config files allowing multiple CIs to live in the same repo.

v0.0.2 - (2021-05-06)

• Updates repo url to public repo

v0.0.1 - (2021-05-06)

• Base release