Understanding OpenAPI → Postman
Spec into collection, ready to click.
What the conversion preserves, where the formats disagree, and the testing workflow this enables.
Two formats, same API.
OpenAPI describes the API as a contract. Postman describes the API as a folder of clickable requests. The two formats overlap heavily but aren't identical — OpenAPI is declarative and machine-first; Postman Collection is interactive and human-first. Converting OpenAPI → Postman lets API consumers start exploring without writing any code; converting the other way is rarer because Postman's free-form fields don't always round-trip.
What converts cleanly.
Every path + method becomes a Postman request. Path parameters become Postman variables. Query parameters and headers map directly. Request bodies withexamples in the spec become the request body in Postman. Authentication (Bearer, API key, OAuth client credentials) maps to Postman's auth presets. Tags become folders. The default conversion produces something usable from the first import.
What loses fidelity.
OpenAPI's response schemas (the documented shape of 200/404/etc.) don't have a direct Postman equivalent — they become test scripts that validate the response shape, or disappear entirely. oneOf request bodies become a single example. Server-side validation rules (regex patterns, min/max) become Postman test scripts if the converter is fancy, prose comments otherwise.
A worked import.
A petstore spec with three endpoints (GET /pets, POST /pets, GET /pets/{id}) imports as a Postman collection with three requests, a {baseUrl} variable set to the spec's first server, the POST body populated from the example, and an Auth tab configured for Bearer. Five seconds from drag-drop to first 200. Adding the same collection to a CI workflow with newman runs the requests as integration tests.
Petstore spec
3 endpoints
OpenAPI YAML → Postman collection JSON.
GET /pets, POST /pets, GET /pets/{id}
= Importable, runnable, automatable
Postman → tests.
A Postman collection isn't just for clicking. newman (Postman's CLI) runs the collection from a command line; newman run collection.json executes every request and reports pass/fail. Wire newman into CI and the collection becomes a contract-test suite. The OpenAPI spec is the source of truth; Postman is the interactive face plus the assertion harness; newman is the automation.
When to keep both.
Teams that ship OpenAPI publicly often maintain a corresponding Postman collection as a "click to try" affordance — developer-relations gold, because it lowers the time-to-first-200 from minutes to seconds. The collection is generated from the spec and republished on every spec change; CI runs the collection against staging to catch drift. The pattern works; treating Postman as the source of truth doesn't.