How can OpenAPI be used to generate Postman collections?

How can OpenAPI be used to generate Postman collections? #

Postman is the most widely used tool for API testing and exploration. A Postman collection is an organized set of API requests that teams use for manual testing, automated test runs, documentation, and onboarding. Rather than building collections by hand — entering each endpoint’s URL, parameters, headers, and body individually — teams can generate them automatically from an OpenAPI document. This approach saves significant time, ensures the collection stays in sync with the API specification, and produces a consistent starting point for test authoring.

Why Generate Collections from OpenAPI? #

Maintaining a Postman collection manually alongside an OpenAPI document creates duplication and drift. As the API evolves — new operations are added, parameters change, request bodies are updated — both documents need to be updated independently. Generation from OpenAPI solves this by making the OpenAPI document the single source of truth:

  • Every operation in the OpenAPI document becomes a request in the collection.
  • Parameter definitions become pre-populated query, path, and header parameters.
  • Request body schemas become example request bodies.
  • Response schemas and examples are attached to requests for reference.
  • Authentication schemes from the OpenAPI document are translated into Postman’s authorization configuration.

Method 1: Import Directly in Postman #

The simplest approach is to import the OpenAPI document directly into Postman:

  1. Open Postman and click Import in the top-left corner.
  2. Select your OpenAPI YAML or JSON file, or paste the document URL.
  3. Postman offers two import modes:
    • API — imports the document as an API definition in the API Builder, from which collections can be generated and kept in sync.
    • Collection — generates a standalone collection directly.
  4. Select Postman Collection and click Import.

Postman maps OpenAPI fields to collection structure:

  • tags → folder names within the collection
  • paths[path][method].summary → request name
  • paths[path][method].description → request description
  • parameters → pre-populated query, path, and header params
  • requestBody → request body (JSON, form, multipart)
  • servers[0].url → base URL variable
  • security → authorization configuration

The resulting collection is immediately usable for exploratory testing.

Method 2: openapi-to-postmanv2 (CLI) #

openapi-to-postmanv2 is Postman’s official open-source Node.js library for programmatic conversion. It is the same engine used internally by Postman’s import UI and is suitable for automation pipelines.

Installation #

npm install -g openapi-to-postmanv2

Usage #

openapi2postmanv2 -s openapi.yaml -o collection.json -p

The -p flag enables “pretty print” for readable JSON output. The output is a Postman Collection v2.1 JSON file that can be imported into Postman or run directly with Newman.

Programmatic Usage #

const Converter = require('openapi-to-postmanv2');
const fs = require('fs');

const openapiContent = fs.readFileSync('openapi.yaml', 'utf8');

Converter.convert({ type: 'string', data: openapiContent }, {}, (err, result) => {
  if (result.result) {
    fs.writeFileSync('collection.json', JSON.stringify(result.output[0].data, null, 2));
  }
});

Conversion Options #

The converter supports a rich set of options to control the output:

  • folderStrategy — organize requests by tag (Tags) or by path (Paths).
  • requestNameSource — use the operation summary or operationId as the request name.
  • parametersResolution — how to resolve $ref schemas: Schema (use schema descriptions) or Example (use example values).
  • exampleParametersResolution — use example values from the schema or generate from schema.
  • enableOptionalParameters — include optional parameters as disabled params in the collection.

Method 3: Postman API (Programmatic Import) #

For CI/CD pipelines where the collection should automatically update in a Postman workspace whenever the OpenAPI document changes, the Postman API enables programmatic collection creation and updates:

# Convert OpenAPI to Postman collection
openapi2postmanv2 -s openapi.yaml -o collection.json -p

# Upload to Postman workspace
curl -X POST https://api.getpostman.com/collections \
  -H "X-Api-Key: $POSTMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d @collection.json

To update an existing collection (avoiding duplicates on each run):

curl -X PUT https://api.getpostman.com/collections/$COLLECTION_ID \
  -H "X-Api-Key: $POSTMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d @collection.json

This pattern can be integrated into GitHub Actions or other CI systems to keep the Postman workspace current after every merge to the main branch.

Method 4: Redocly CLI #

Redocly CLI provides an openapi to bundle workflow that can be combined with conversion tools. While Redocly does not natively export Postman collections, it is commonly used upstream to bundle multi-file OpenAPI documents into a single file before passing them to the Postman converter.

Running Generated Collections with Newman #

Newman is Postman’s CLI collection runner. Once a collection is generated from the OpenAPI document, it can be run against any environment:

npm install -g newman

newman run collection.json \
  --environment environment.json \
  --reporters cli,junit \
  --reporter-junit-export results.xml

This enables automated regression testing in CI/CD pipelines. The JUnit XML output integrates with CI platforms like Jenkins, GitHub Actions, and GitLab CI to display test results as part of the build report.

Enriching Generated Collections with Tests #

Generated collections contain requests but no test scripts. To make them useful for automated validation, test scripts should be added to each request. These can be authored manually in Postman or added programmatically using Newman’s collection API or the Postman Collection SDK:

// Test script added to a request
pm.test("Status code is 200", () => {
  pm.response.to.have.status(200);
});

pm.test("Response has required fields", () => {
  const body = pm.response.json();
  pm.expect(body).to.have.property('id');
  pm.expect(body).to.have.property('email');
});

A practical strategy is to generate the collection on each CI run (ensuring it reflects the latest OpenAPI document) but maintain test scripts separately in a Postman environment or as a script layer applied on top of the generated base collection.

Keeping Collections in Sync #

The key challenge with generated collections is keeping them current as the OpenAPI document evolves. Recommended practices:

  • Regenerate on every merge — use a CI step to regenerate the collection and push it to Postman via the API whenever the OpenAPI document changes.
  • Use environments for base URLs — store the base URL as a Postman environment variable ({{baseUrl}}) so the collection works across development, staging, and production.
  • Separate generated from hand-authored — maintain two collections: a generated one (auto-updated) and a curated one (with test scripts) that is periodically reconciled with the generated version.

Conclusion #

Generating Postman collections from OpenAPI documents eliminates the manual effort of maintaining two parallel API descriptions. Whether using Postman’s built-in import, the openapi-to-postmanv2 CLI, or the Postman API for programmatic updates, teams can keep their testing workspaces in sync with the authoritative API specification. Combined with Newman for CI/CD integration, this workflow brings automated, specification-driven API testing within reach of every team that maintains an OpenAPI document.

Last updated on April 30, 2026.

This website is not affiliated with the OpenAPI Initiative.