How to generate Postman collections from OpenAPI automatically (August 2026)

Most Postman collections are maintained by hand. Someone ships an endpoint, someone else remembers to add the matching request, and two releases later the collection describes an API that no longer exists. Every generation path worth using treats the collection as a build artifact of the API specification instead of a document a person owns, the same reasoning that produces API reference documentation and client libraries from one source. The conversion step itself is solved and has been for years, so the quality of a generated collection is determined almost entirely by two things that sit on either side of it: how complete the OpenAPI spec is going in, and whether regeneration is wired into CI coming out.

TLDR:

• Postman generates collections natively from OpenAPI 2.0, 3.0, and 3.1, so the conversion is a configuration decision rather than an engineering project.
• Collection quality is bounded by spec quality. operationId, tags, examples, securitySchemes, and servers map directly onto request names, folders, saved examples, auth, and collection variables.
• Automate regeneration with openapi-to-postmanv2, the Postman API, or Portman in CI instead of clicking import after every release.
• Two-way sync in Spec Hub keeps a collection aligned with its spec, but it does not support multi-file OpenAPI specs and it leaves orphan requests behind unless you opt into removing them.
• Fern retired its own Postman collection generator in favor of Postman's native import, and focuses upstream on keeping the OpenAPI definition that feeds the collection validated, current, and example-rich.

What a generated Postman collection actually contains

Generation is a structural mapping, not an interpretation. Knowing which OpenAPI field lands where in the collection tells you exactly which parts of your spec to fix before you generate anything.

The practical consequence: an operation with no summary, no tags, and no examples becomes a request named after its raw URL path, filed in a path-shaped folder, with a placeholder body. The generator did its job. The spec did not.

Step 1: fix the spec before you generate anything

This is the step teams skip, and it is the one that determines whether developers find the collection usable or abandon it after the first 401.

Give every operation an operationId and a summary

Postman lets you choose whether request names come from the operation summary, the operationId, or the URL path. Path-based names produce a collection full of /v1/users/{userId}/subscriptions entries that are hard to scan. Summaries produce Cancel a subscription. Set both fields on every operation so the naming strategy is a choice rather than a fallback.

Treat tags as folder design

Folders come from tags by default, so tags stop being metadata and start being information architecture. An API with 200 operations and three tags generates three enormous folders. An API where every operation carries a distinct tag generates 200 folders with one request each. Group tags around the resources developers actually work with, and keep the tag list stable across releases so folder paths do not churn on every regeneration.

Put real examples in the spec

Examples are the single highest-leverage input. Without them, generated requests arrive with "string" and 0 placeholders in every body field, and developers have to reconstruct a valid payload before the collection is useful. With them, the first request in the collection is one that actually returns a 200.

OpenAPI's native example and examples fields cover the basic case but cannot associate a specific request with the response it produces. Fern's x-fern-examples extension links request and response pairs at the operation level and supports multiple named examples per endpoint, which is what you want when one endpoint behaves differently for different inputs. For specs that are already large and already thin on examples, fern api enrich merges AI-generated examples into portable OpenAPI examples, so the enrichment stays in the spec file rather than living in a vendor's database.

Declare security schemes and servers explicitly

Auth is where generated collections most often fail on first use. Postman reads components.securitySchemes to configure collection-level or per-request auth, so a spec that omits them produces requests with no auth configured at all. The same applies to servers: declared server URLs become collection variables, and a missing servers block leaves developers editing the host on every request. If your API has staging and production hosts, declare both so they arrive as switchable variables.

Step 2: pick a generation path

Four approaches cover essentially every workflow. They are not mutually exclusive, and most mature setups use two.

Postman's native import and Spec Hub

The default. Spec Hub supports OpenAPI 2.0, 3.0, and 3.1, plus AsyncAPI and Smithy for WebSocket APIs, and generates a collection with folders, requests, and response examples from the spec. Generation is configurable: request naming source, folder strategy (paths or tags, optionally nested), whether optional parameters and deprecated operations are included, and whether auth details are added to each request or inherited from the parent.

For OpenAPI specifically, Postman also supports two-way sync, so spec updates push into the collection and collection changes can flow back into the spec. That is the closest thing to a maintenance-free setup, with the caveats in Step 4.

openapi-to-postmanv2 for scripted conversion

openapi-to-postmanv2 is the converter Postman built for its own OpenAPI import support and open sourced, published on npm and usable as a library or a CLI. It handles OpenAPI 3.0, 3.1, and Swagger 2.0. Reach for it when you want the collection JSON as a file in your repo, committed and reviewable in pull requests, rather than as an object living in a workspace:

openapi2postmanv2 -s openapi.yml -o postman-collection.json -p \
  -O folderStrategy=Tags,requestNameSource=Fallback,includeAuthInfoInExample=false

The conversion options matter more than they look. folderStrategy takes Tags or Paths, requestNameSource takes URL or Fallback (which names requests from description, then operationId, then the URL), and includeAuthInfoInExample=false keeps auth values out of generated examples, which is the setting you want if the collection JSON is going anywhere near a public repo.

The Postman API for programmatic publishing

When the collection needs to live in a shared workspace rather than a repo, the Postman API exposes collection endpoints a pipeline can call directly. Two patterns work. The Collections API can import an OpenAPI definition to create a collection outright, which skips the local conversion step entirely. Or you convert the spec locally and replace an existing collection with a v2-format body at a known collection UID. The update endpoint replaces the collection wholesale, so treat the workspace copy as read-only output and keep every intentional change in the spec.

Portman when you want tests, not just requests

Portman converts an OpenAPI spec into a Postman collection and injects a generated test suite, then runs it through Newman. It produces contract tests that assert responses match the schemas declared in the spec, variation tests that strip required fields or send wrong content types to check error handling, and integration tests that chain requests through create-read-update-delete flows. If the goal is a collection that runs in CI as a check rather than one developers click through, this is the path.

Step 3: regenerate on every spec change

Manual regeneration decays for the same reason manual collections do. The trigger should be a spec change, not a calendar reminder.

For teams whose spec is generated from server code, fern api update pulls the latest OpenAPI spec from a configured origin, which gives CI a deterministic way to fetch the current definition before anything downstream runs. Validate before converting: fern check validates the API definition and configuration, and a spec that fails validation should stop the pipeline rather than generate a broken collection. A minimal job looks like this:

fern api update          # pull the current spec from its origin
fern check               # fail the build on an invalid definition
openapi2postmanv2 -s fern/openapi/openapi.yml -o postman-collection.json -p
newman run postman-collection.json --env-var baseUrl=$STAGING_URL

Committing the generated collection back to the repo turns every spec change into a visible diff in the collection, which is the same docs-as-code property that makes generated documentation reviewable. A reviewer catches that renaming a field emptied three request bodies before developers hit it.

Step 4: keep sync from quietly corrupting the collection

Automated sync introduces failure modes that manual maintenance does not, and all of them are avoidable if you know about them going in.

• Orphan requests accumulate by default. When an operation is renamed, Postman's sync creates a new request and leaves the old one in place unless "remove orphan requests" is enabled. Left off, the collection grows a long tail of endpoints that no longer exist.
• Multi-file specs are not supported for sync. Postman does not support syncing collections to multi-file OpenAPI specifications. If your spec is split across $ref-linked files, bundle it into a single document as a build step before generation, and keep the multi-file layout as the authoring format.
• Local edits to generated collections are temporary. Any test script, header, or renamed request added directly in the workspace is at risk on the next regeneration. Anything that must survive belongs in the spec, in a Portman config, or in a Postman environment.
• Environment values do not belong in the collection. Base URLs, tokens, and tenant IDs go in environments and variables, not in the generated collection JSON. This keeps secrets out of an artifact that is frequently made public.

Failure modes worth designing around

Beyond sync mechanics, three characteristics of OpenAPI-to-collection conversion cause most of the complaints developers file.

Polymorphic schemas flatten. oneOf, anyOf, and discriminated unions have no direct representation in a Postman request body. The converter resolves to one branch, so a generated request for a polymorphic endpoint shows a single valid shape and silently hides the others. Where an endpoint accepts genuinely different payloads, define a named example per variant in the spec so each one arrives as its own saved example.

Auth in examples leaks credentials. Converters can embed auth information into generated example requests. If the generated JSON is committed, published, or forked, whatever sat in that field goes with it. Set includeAuthInfoInExample=false, keep tokens in environments or Postman Vault where secrets resolve at runtime instead of being stored in the collection, and scan generated collection artifacts in CI the same way you scan any other build output.

Large collections stop being navigable. A 300-operation API produces a 300-request collection, and folder strategy is the only structural lever you get. Nested folders by tag help; publishing separate collections per API version or per audience helps more. This is the point where a collection alone stops covering the use case and an API Explorer embedded in the reference documentation does better, because developers reach the endpoint they need by reading rather than by scrolling a tree.

Where collections stop and SDKs start

A collection is an exploration and testing surface. It gets a developer to a first successful call and gives QA something to run in CI. It is not what anyone ships to production, because a saved request carries no types, no retry behavior, no pagination handling, and no compile-time signal when the API changes.

The same OpenAPI spec that generates the collection generates the client libraries that replace it. Fern produces idiomatic SDKs in TypeScript, Python, Go, Java, C#, PHP, Ruby, Swift, and Rust from one definition, and the request examples in that definition also render as SDK code snippets in the API reference. The useful arrangement is both: the collection for exploration, the SDK for integration, and a single spec keeping the two from disagreeing.

How Fern fits into a Postman collection workflow

Fern's own Postman collection generator is no longer actively maintained; the documented guidance is to import your OpenAPI specification into Postman directly. Fern's role in this workflow is upstream: fern check validates the definition, fern api update keeps it current with the server implementation, x-fern-examples and fern api enrich make it example-rich enough to generate a collection developers can run unmodified, and fern export writes a standard OpenAPI file back out so the spec is never trapped in a vendor format. Fern Docs also generates a documentation site directly from a Postman collection, with an API reference, sample code, and an interactive API Explorer, for teams whose collection is the artifact they already maintain. Fern has been a Postman company since January 2025, which is why the integration points toward Postman's native import rather than duplicating it.

Final thoughts on generating Postman collections from OpenAPI

Converting OpenAPI to a Postman collection is not the hard part and has not been for a long time. The collection is a build artifact, and the two things that decide whether it is worth publishing both live outside the converter: a spec with real operationIds, deliberate tags, declared security schemes, and linked request and response examples, and a CI job that regenerates on every spec change instead of on request. Get those right and the collection stops being a maintenance item. Book a demo to see how Fern keeps the OpenAPI definition behind your collection, documentation, and SDKs accurate as your API changes.

FAQ

How do I convert an OpenAPI file to a Postman collection?

Import the spec into Postman, which supports OpenAPI 2.0, 3.0, and 3.1 and generates a collection with folders, requests, and response examples. For a scripted conversion, run the open source openapi-to-postmanv2 CLI against the spec file and write the collection JSON to disk. Both paths read the same fields, so the output quality depends on the spec, not the tool.

Can a Postman collection stay in sync with an OpenAPI spec automatically?

Yes, through two-way sync in Spec Hub for OpenAPI specs, which pushes spec updates into the collection and can reflect collection changes back into the spec. Two limits matter: syncing to multi-file OpenAPI specifications is not supported, so bundle to a single document first, and renamed endpoints leave orphan requests behind unless the "remove orphan requests" option is enabled.

Does Fern generate Postman collections?

Not anymore. Fern's Postman collection generator is no longer actively maintained, and the documented recommendation is to import your OpenAPI specification directly into Postman. Fern focuses on the definition that feeds the collection, validating it with fern check, keeping it current with fern api update, and enriching its examples, and separately supports generating a Fern Docs site from an existing Postman collection.

What is the best way to generate a Postman collection in CI/CD?

Validate the spec, convert it with openapi-to-postmanv2, and either commit the collection JSON to the repo or publish it to a workspace with the Postman API's collection update endpoint. Trigger the job on spec changes rather than on a schedule. If the collection is meant to run as a check, use Portman to inject contract and variation tests and execute them with Newman in the same pipeline.

Do I still need SDKs if I publish a Postman collection?

Yes, because they solve different problems. A collection helps a developer explore the API and confirm a request works; an SDK is what they ship, with types, retries, pagination, and error handling built in. Generating both from one OpenAPI spec means the collection and the client libraries describe the same API, which is the failure mode hand-maintained collections cause.