openapi-to-postman

openapi-to-postmanv2 is Postman’s official converter for turning an OpenAPI 3.0, OpenAPI 3.1, or Swagger 2.0 specification into a Postman Collection, usable either as an importable Node module or as the openapi2postmanv2 CLI. Beyond a one-shot conversion, it can detect and bundle multi-file specs ($ref-linked YAML/JSON split across files) into a single document, validate that an input is well-formed OpenAPI/Swagger before conversion, and expose rich per-request/per-schema conversion options (folder strategy, auth handling, example generation) through a shared options schema used by both the library and the CLI.

Its most distinctive capability is syncCollection: rather than regenerating a Postman Collection from scratch every time a spec changes (which would blow away manual edits a team made to an existing collection), it diffs the new spec against the current collection and merges in additions, renamed fields, and updated request bodies/headers/query params while preserving hand-authored requests and folders unless explicitly told to prune orphans. This makes it suitable for CI pipelines that keep a living Postman Collection in sync with an evolving API spec over time, not just for one-off spec-to-collection conversions.

What You Get

• A convert/convertV2 API that turns an OpenAPI 3.0/3.1 or Swagger 2.0 document into a Postman Collection object or JSON file
• A validate function to check a spec is well-formed before attempting conversion, with a reason string on failure
• Multi-file spec support: detectRootFiles/detectRelatedFiles/bundle locate and merge a $ref-split specification into one document
• syncCollection, which merges spec changes into an existing Postman Collection instead of overwriting it, with syncExamples and deleteOrphanedRequests options
• A CLI (openapi2postmanv2) sharing the same options schema as the library, for use directly from a terminal or CI step without writing Node code

Common Use Cases

• Generating a Postman Collection from an API’s OpenAPI spec as part of a documentation or release pipeline
• Keeping a team’s existing Postman Collection in sync with an evolving OpenAPI spec without discarding manually added requests or examples
• Validating that an OpenAPI/Swagger file is convertible before running it through downstream tooling
• Bundling a multi-file OpenAPI specification (split across several YAML/JSON files) into a single document for distribution or further processing

Under The Hood

Architecture The package is built around a single orchestration class, SchemaPack (lib/schemapack.js), which every public function in the thin index.ts facade (convert, convertV2, validate, bundle, syncCollection, etc.) constructs and delegates to; the same class backs the CLI in bin/openapi2postmanv2.js via the compiled dist/ output. Internally it dispatches across two coexisting implementations: a legacy pipeline in lib/ (schemapack.js, parse.js, deref.js, bundle.js, version-specific 30X/31X/32X utils) handling validation, $ref resolution and the original v1/v2 conversion, and a newer TypeScript layer in libV2/ split into CollectionGeneration (assembles Postman collections/folders/auth from parsed OpenAPI operations) and SpecificationCollectionSyncing (a dedicated merge engine with per-concern mergers - BodyMerger, HeaderMerger, QueryParamMerger, RequestMerger, ResponseMerger, UrlMerger, plus PathMatcher/ParameterExtractor - that reconciles a changed spec into an existing collection without discarding user edits). Because everything funnels through SchemaPack’s constructor and validate() step, that class is the one place a change ripples to both the CLI and every library entry point.

Tech Stack Node >=18, with an in-progress migration from plain JS (lib/) to TypeScript (libV2/SpecificationCollectionSyncing, index.ts), compiled via tsc per tsconfig.json. Core dependencies: postman-collection (the official Postman SDK for constructing collection/URL objects), swagger2openapi (normalizes Swagger 2.0 input up to OpenAPI 3), ajv/ajv-draft-04/ajv-formats (JSON Schema validation), oas-resolver-browser (external $ref resolution), js-yaml and yaml (spec parsing), graphlib (graph utilities, used for dependency/cycle handling across split files), and commander (CLI argument parsing in bin/). No database or web-server layer - this is a pure conversion library shipped as a compiled dist/ bundle plus a CLI wrapper.

Code Quality The repo carries an extensive test suite - unit, integration, and system tests under test/, backed by a large fixture corpus (test/data/) covering valid and invalid OpenAPI 3.0/3.1/3.2-track and Swagger 2.0 documents, run via mocha with chai assertions and nyc coverage reporting, plus a dedicated test-lint script and an eslint config (eslint-plugin-security, eslint-plugin-import, eslint-plugin-jsdoc, eslint-plugin-mocha) enforcing style across contributions. A GitHub Actions workflow runs the test suite on every change. Errors are raised through a small custom error hierarchy (UserError/OpenApiErr) rather than being swallowed, and TypeScript sections get compile-time type checking while the still-JS legacy code relies on JSDoc annotations for editor-level typing.

API Design The public surface in index.ts is compact and consistent - convert/convertV2/convertV2WithTypes, validate, getMetaData, mergeAndValidate, bundle, detectRootFiles/detectRelatedFiles, and syncCollection - all constructed from the same SchemaPack class and exported both as named functions and as a default object, plus the SchemaPack class itself for consumers who want lower-level control. The CLI is a thin wrapper generated from the same getOptions()/getSyncOptions() metadata the library exposes, so command-line flags and programmatic options never drift apart. The main rough edge is that conversion options are documented in separate OPTIONS.md/SYNC_OPTIONS.md files rather than inline in the TypeScript types, so discovering the full option surface requires reading docs rather than autocomplete alone.