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 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 so you know
whether consumers need a heads-up.

The 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.