This example contains the setup of Portman where all the Portman CLI options are managed via a JSON/YAML file.

use-case: Run portman in CI/CD pipeline and pass the CLI options as part of a versioning system like GIT.

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

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

{
  "local": "./examples/cli-options/crm.openapi.yml",
  "baseUrl": "http:https://localhost:3050",
  "output": "./examples/cli-options/crm.postman.json",
  "portmanConfigFile": "./examples/cli-options/portman-config.crm.json",
  "postmanConfigFile": "./examples/cli-options/postman-config.crm.json",
  "envFile": "./examples/cli-options/.lead.env",
  "includeTests": true,
  "syncPostman": false,
  "syncPostmanCollectionIds": false,
  "runNewman": false,
  "oaRename": "CRM API - Test suite"
}

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

local: ./examples/cli-options/crm.openapi.yml
baseUrl: 'http:https://localhost:3050'
output: ./examples/cli-options/crm.postman.json
portmanConfigFile: ./examples/cli-options/portman-config.crm.json
postmanConfigFile: ./examples/cli-options/postman-config.crm.json
envFile: ./examples/cli-options/.lead.env
includeTests: true
syncPostman: false
syncPostmanCollectionIds: false
runNewman: false
oaRename: 'CRM API - Test suite'

In our example, we want to define all the CLI options upfront and store it in GIT, so that it can be executed in a CI/CD pipeline

• local: refers to the local OpenAPI file location to port to postman collection (examples/cli-options/crm.openapi.yml)
• baseUrl: overrides spec baseUrl with the defined value to use in the test suite
• output: refers to the location where the generated Postman collection file be stored (examples/cli-options/crm.postman.json)
• portmanConfigFile: refers to the portman configuration file with Portman settings, like Postman values to be replaced, overwritten, ... (examples/cli-options/portman-config.crm.json). This can be in JSON or YAML format.
• postmanConfigFile: refers to the openapi-to-postman configuration file location with settings on how to transform and organize the Postman collection (examples/cli-options/postman-config.crm.json)
• envFile: refers to the .env file you want to use for environment variable injection (/examples/cli-options/.env)
• includeTests: a toggle to generate Postman tests based on the OpenAPI specification
• postmanUid: refers to the collection ID to upload the generated collection to your postman app
• syncPostman: a toggle to upload the newly created collection to the Postman app
• syncPostmanCollectionIds: Synchronises the IDs of newly created postman collections with those already on Postman, useful when you want to use Postman pull request.
  ⚠️ If you have not specified example in some properties in your OpenApi schemas, the ids of the response examples will be kept but the property values will be generated again by the faker when using openapi-to-postman and you will still have a lot of changes in your pull request. To avoid this, you need to add the exampleParametersResolution option with the value "Schema" which will set the type of the property instead of a fake example (This could be resolved when the schemaFaker option is available on openapi-to-postman).
• runNewman: a toggle to run Newman on a newly created collection
• oaRename: Change the OpenAPI title & Postman collection name to 'CRM API - Test suite'. This might be handy if you want to have your original Postman collection and your Portman generated Postman collection as separate collections.

BEFORE

AFTER

One of the Portman CLI options is to test the generated Postman collection, through Newman. Portman has the option to support this out of the box. All Newman configuration options to run Newman can be passed along.

Here are some several way run & manage the Newman execution in Portman, using the following parameters

• runNewman: a toggle to run Newman on a newly created collection
• newmanRunOptions: JSON (stringified) object to pass options for configuring the Newman test run
• newmanOptionsFile: Path to Newman options file to pass options for configuring Newman

You can reference a Newman options file in JSON format, and pass that along with a Portman CLI parameter.

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

Example of a newman-options.json config file:

{
  "environment": "./tmp/crm/postman-dev.env.json",
  "iteration-count": 5,
  "ignore-redirects": true,
  "insecure": true
}

Another option to set the Newman options by passing the options as an object on the CLI.

portman -u https://specs.apideck.com/crm.yml -c ./tmp/crm/portman-config.json --runNewman --newmanRunOptions '{"environment":"./tmp/crm/postman-dev.env.json","iteration-count": 5}'

If you use to the cliOptionsFile file to centralize your Portman setting, you can simply include the Newman options as an object.

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

Example of a Portman CLI options file:

{
  "local": "./examples/cli-options/crm.openapi.yml",
  "baseUrl": "http:https://localhost:3050",
  "output": "./examples/cli-options/crm.postman.json",
  "portmanConfigFile": "./examples/cli-options/portman-config.crm.json",
  "postmanConfigFile": "./examples/cli-options/postman-config.crm.json",
  "envFile": "./examples/cli-options/.lead.env",
  "includeTests": true,
  "syncPostman": false,
  "runNewman": true,
  "newmanRunOptions": {
    "environment": "./tmp/crm/postman-dev.env.json",
    "iteration-count": 5,
    "ignore-redirects": true,
    "insecure": true
  }
}