openapi-to-postmanv2 turns a specification into a collection you can keep in step

Two jobs that look alike and are not

The first thing to separate is converting and syncing, because the CLI supports both and they solve different problems. Converting takes a specification and produces a collection, which is what you want the first time. Syncing takes a specification and an existing collection and updates the collection, which is what you want every time after that. The distinction matters because a collection accumulates things a specification does not describe, environment variables, test scripts, saved examples, the order a team arranged folders in, and a converter that overwrites the file throws all of that away. The project treats syncing as a first-class feature with its own options file, SYNC_OPTIONS.md, and its own set of flags, and the repository carries a separate CLI flag namespace for it. The audience is a team that keeps a Postman collection in version control next to the specification and wants the two to converge.

The command line, and the options that matter

The CLI is openapi2postmanv2 with a set of options, and most of them exist because the output shape is not obvious. The -s or --spec flag gives the specification path, -o or --output the destination file, and -p or --pretty pretty prints the collection object while writing it. The -i or --interface-version flag chooses between the v2 and v1 converter interfaces, with v2 as the default. The -O or --options flag supplies converter options as key=value pairs, and -c or --options-config supplies the same options through a config file, with the details in OPTIONS.md. The -t or --test flag runs the converter against an in-built sample specification, which is a fast way to check an installation. And -v prints the version. A typical conversion looks like this:

openapi2postmanv2 -s spec.yaml -o collection.json -p -O folderStrategy=Tags,includeAuthInfoInExample=false

and the same thing with a config file instead of inline options is:

openapi2postmanv2 -s spec.yaml -o collection.json -p  -c ./examples/cli-options-config.json

Sync, and the option that stops you losing work

The sync commands take the specification, the collection to update and the output file:

openapi2postmanv2 -s spec.yaml --sync collection.json -o synced-collection.json

The options can be given inline as a comma separated list, for example --sync-options syncExamples=true, or through a JSON file with --sync-options-config, and the example configuration is two keys:

{
  "syncExamples": true,
  "deleteOrphanedRequests": false
}

The two documented options are the whole public surface, and the second one is the one with the interesting default. syncExamples, false by default, decides whether response examples from the specification are synced into the existing collection responses. deleteOrphanedRequests, also false by default, decides whether requests and folders that exist in the collection but no longer exist in the specification are deleted, and when it is disabled, and it is by default, such orphans are preserved to avoid unintentional data loss. That default is the right one, because a request that a colleague added by hand and that is not in the spec yet is not garbage, and a sync that silently removes it will be noticed, and then the sync will be run with the flag off.

The Node module exposes convert, sync and validate

Used as a library, the package is imported with require, and it exposes several functions. The convert function takes in your OpenAPI 3.0, 3.1 and Swagger 2.0 specification, in YAML or JSON, and converts it to a Postman collection, with the signature convert(data, options, callback). The data argument has three accepted forms, a file with a path, a string holding the entire specification, or a json object. The options object is where the output shape is decided, and the example shows schemaFaker, requestNameSource set to fallback, and an indentCharacter, with all three optional. The callback receives the standard error-first shape, and the result is an object with a result flag and an output array whose entries have a type of collection and the collection data. The syncCollection function does the same job as the sync flag, updating an existing collection from a specification, and the package also provides a validate function and documents a ConversionResult type, with the full option list in OPTIONS.md and the sync options in SYNC_OPTIONS.md.

Options exist because a specification is not a collection

The options that show up in the documented command lines are the interesting part, because each one is a decision about how a schema becomes a request. folderStrategy=Tags is the obvious one, and it decides whether the collection is organised by tag or by path, which is the difference between a collection that reads like the API and one that reads like the file system. requestParametersResolution=Example says that example values from the specification are used for the request parameters rather than placeholders. includeAuthInfoInExample=false keeps the authentication details out of the generated examples. Then there are the two options that exist because the converter hit a wall, optimizeConversion=false and stackLimit=50, and the documentation explains that the third usage example passes them to avoid any "Too many levels of nesting to fake this schema" kind of errors present in the converted collection. The schema faking is the mechanism, because a specification describes a schema and a collection needs a concrete body, and a deeply nested schema has to be faked to some depth, and the stack limit is where you decide how deep the faking goes.

Two converter implementations and a Postman plugin manifest

The repository layout shows how the project is arranged, with lib/ and libV2/ as the two implementations that correspond to the v1 and v2 interface versions the -i flag chooses between, index.ts as the entry point, types/ for the TypeScript types, bin/ for the command line, and assets/, examples/, scripts/ and test/ around them. The examples/ directory is the test corpus and it is worth a look, because it holds the awkward documents: a petstore and an expanded petstore, the classic sampleswagger.yaml, a callback example, a link example, an api-with-examples.yaml, uspto.yaml, a recursive.json and the two CLI option config files. That last pair, recursive.json and the nesting errors in the command line examples, is the same problem in two places. The package.json also carries a com_postman_plugin block, which is the manifest that describes the converter to Postman itself, declaring the plugin_type as importer, the name and source_format as OPENAPI3.0, and a sample_input with a small petstore document, so the same converter is used inside Postman and from the command line.

Editorial conclusion

openapi-to-postmanv2 is the right tool when a Postman collection has to be produced from a specification, and especially when that collection is a living artefact, because the sync mode with its orphan protection is the difference between a collection that tracks the spec and one that quietly drifts. It is the wrong tool if you want the collection to be the source of truth, since the converter is a one way path from spec to collection, and it is the wrong tool for a specification with constructs the converter cannot express, where the schema faking options exist precisely to paper over a gap. Before you wire it into a pipeline, read OPTIONS.md, because the folder strategy, the parameter resolution and the stack limit change the shape of the output, and check what your spec does to the nesting depth, since the error about too many levels of nesting to fake this schema is a known failure mode.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. postmanlabs/openapi-to-postman on GitHub
4. README
5. Releases