Postman collections and OpenAPI: two views of the same API

Almost every team ends up with both artefacts. Someone builds a Postman collection while exploring the API, and someone else writes an OpenAPI spec because the docs site, the SDK generator and the mock server all want one. They drift apart within a sprint.

They are not the same document

A Postman collection is a list of **concrete requests**: this URL, these headers, this body, plus scripts that run before and after. It is a record of calls that worked.

An OpenAPI document is a **contract**: these paths exist, these parameters are required, this is the response schema. It says nothing about what you happened to send last Tuesday.

That difference decides what survives a conversion. Concrete values become examples and schemas; scripts, environments and test assertions have no OpenAPI equivalent at all.

Postman → OpenAPI: what a good conversion does

• Group requests by URL path, not by folder, so `GET /orders` and `POST /orders` land on the same path item.
• Turn `:orderId` segments and `{{orderId}}` variables into `{orderId}` path parameters marked required.
• Promote query string entries to query parameters, keeping the observed value as `example`.
• Infer a JSON Schema from raw JSON bodies — types, nested objects, array item types — rather than dumping a string blob.
• Map folders to tags so the generated docs keep their structure.

What you always fix by hand afterwards: response schemas (a collection rarely records them), descriptions, and auth. Run the result through the [API Contract Analyzer](/tools/api/api-contract-analyzer) and it will list exactly what is missing.

OpenAPI → Postman: what a good conversion does

Going the other way is more mechanical, because the spec has more information than the collection needs:

• One folder per tag, one request per operation.
• Path templates back to `:param` form, with Postman path variables filled from schema examples.
• Query parameters added but disabled when they are optional, so the request works out of the box.
• A request body generated from the schema — real examples where the spec provides them, typed placeholders where it does not.
• No `servers` entry? Emit a `{{baseUrl}}` collection variable instead of hard-coding a host.

That last point matters more than it looks. A collection with a baseUrl variable can be pointed at staging, production or a local mock without editing a single request.

Keeping them in sync

Treat the OpenAPI document as the source of truth and regenerate the collection whenever the spec changes. Before you publish a new version, diff the old and new specs with the [API Breaking Change Detector](/tools/api/api-breaking-change-detector) so you know whether consumers need a heads-up.

The [Postman ↔ OpenAPI Converter](/tools/api/postman-openapi-converter) does both directions in the browser — paste JSON or YAML, pick a direction (or let it detect one), and download the result. Nothing is uploaded, which matters when your collection still has a real token sitting in a header.