Postman sync

With --syncPostman, Portman uploads the generated collection to the Postman app through the Postman API. This is optional: Portman does not require a Postman account, and the generated collection file can always be imported into Postman manually.

Set up the Postman API key

A free or paid Postman account works.

1. Get your Postman API key from your Postman account settings.
2. Go to the root folder of your project.
3. Copy .env-postman-app.example as .env in the root folder of your project.
4. Add your key to the .env file:

POSTMAN_API_KEY=[replace with Postman api key]

Do not commit the .env file to version control if it contains confidential credentials.

Supported .env variables

The CLI options --postmanWorkspaceName and --postmanUid overrule the values in the .env file.

Upload a collection

Upsert the collection, based on the collection name:

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

Overwrite a specific existing collection by its UID:

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

Use --collectionName to set the Postman collection name instead of the OpenAPI title.

Large collections

When a collection gets large, the Postman API compares all requests during an update. This can take some time and even result in 5xx errors. --postmanFastSync syncs with "delete" and "create" operations instead of "update":

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

Using --postmanFastSync results in a new Postman collection and a new Postman UID on every sync.

Cache

Portman caches Postman API data in .portman.cache.json for faster lookups and uploads. To reset it, delete that file or pass --postmanRefreshCache:

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

Postman pull requests

--syncPostmanCollectionIds synchronises the IDs of newly created collection items with those already on Postman, which keeps diffs small when you use Postman pull requests. If some properties in your OpenAPI schemas have no examples, the generated values can still change between runs. Setting the openapi-to-postman parametersResolution option to "Schema" in your Postman config file avoids that.