# graphql-to-postman > Generates a Postman Collection from a GraphQL schema. Latest version **1.0.0** (published 2025-03-07) · Apache-2.0 license · 0 weekly downloads ## Install ```sh npm install graphql-to-postman pnpm add graphql-to-postman yarn add graphql-to-postman bun add graphql-to-postman ``` ## Health **Score 40/100 (D)** — status: stable. Positive: no vulnerabilities; high maintenance score. Warnings: low downloads; no types; no esm support. Negative: stale. ## Facts | | | |---|---| | Version | 1.0.0 | | Published | 2025-03-07 | | First published | 2019-12-10 | | Weekly downloads | 0 | | License | Apache-2.0 | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 0 | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 42 | | Author | Postman Labs | | Maintainers | aravindrajr, postman-admin, gouthamaj, abhijitkane, vshingala, tilak-patel-postman, kdevakumaran | | Keywords | graphql, postman, collection | ## Links - npm: https://www.npmjs.com/package/graphql-to-postman - Repository: https://github.com/postmanlabs/graphql-to-postman - Homepage: https://github.com/postmanlabs/graphql-to-postman#readme - Issues: https://github.com/postmanlabs/graphql-to-postman/issues - npm.io page: https://npm.io/package/graphql-to-postman ## Alternatives - [apollo-link-http-common](https://npm.io/package/apollo-link-http-common.md) — 879.0K weekly downloads - [react-relay](https://npm.io/package/react-relay.md) — 336.8K weekly downloads - [relay-test-utils](https://npm.io/package/relay-test-utils.md) — 181.6K weekly downloads - [@vendure/core](https://npm.io/package/@vendure/core.md) — 14.8K weekly downloads - [@pnpm/deps.graph-sequencer](https://npm.io/package/@pnpm/deps.graph-sequencer.md) — 13.4K weekly downloads ## Recent versions - 1.0.0 (latest) — 2025-03-07 - 0.0.12-beta.2 (beta) — 2023-01-03 - 0.3.0 — 2024-07-10 - 0.2.0 — 2024-07-03 - 0.1.1 — 2024-04-05 - 0.1.0 — 2023-06-06 - 0.0.13 — 2023-03-30 - 0.0.12 — 2023-01-09 - 0.0.12-beta.1 — 2022-12-28 - 0.0.11 — 2021-09-26 - 0.0.10 — 2021-09-26 - 0.0.9 — 2021-04-09 - 0.0.8 — 2021-03-15 - 0.0.7 — 2020-10-23 - 0.0.6 — 2020-07-23 - … 6 more at https://npm.io/package/graphql-to-postman/versions ## README The Postman Logo *Supercharge your API workflow.* *Modern software is built on APIs. Postman helps you develop APIs faster.* # GraphQL to Postman Collection ![Build Status](https://github.com/postmanlabs/graphql-to-postman/actions/workflows/test.yml/badge.svg) ![npm](https://img.shields.io/npm/v/graphql-to-postman.svg) ![npm](https://img.shields.io/npm/dw/graphql-to-postman.svg) #### Contents 1. [Getting Started](#getting-started) 2. [Command Line Interface](#command-line-interface) 1. [Options](#options) 2. [Usage](#usage) 3. [Using the converter as a NodeJS module](#using-the-converter-as-a-nodejs-module) 1. [Convert Function](#convert) 2. [Options](#options) 3. [ConversionResult](#conversionresult) 4. [Sample usage](#sample-usage) 5. [Validate function](#validate-function) 4. [Conversion Schema](#conversion-schema) --- --- ## 💭 Getting Started To use the converter as a Node module, you need to have a copy of the NodeJS runtime. The easiest way to do this is through npm. If you have NodeJS installed you have npm installed as well. ```terminal $ npm install graphql-to-postman ``` If you want to use the converter in the CLI, install it globally with NPM: ```terminal $ npm i -g graphql-to-postman ``` ## 📖 Command Line Interface The converter can be used as a CLI tool as well. The following [command line options](#options) are available. `gql2postman [options]` ### Options - `-s `, `--spec ` Used to specify the GraphQL specification (file path) which is to be converted - `-o `, `--output ` Used to specify the destination file in which the collection is to be written - `-p`, `--pretty` Used to pretty print the collection object while writing to a file - `-i`, `--interface-version` Specifies the interface version of the converter to be used. Value can be 'v2' or 'v1'. Default is 'v2'. - `-O`, `--options` Used to supply options to the converter, for complete options details see [here](/OPTIONS.md) - `-c`, `--options-config` Used to supply options to the converter through config file, for complete options details see [here](/OPTIONS.md) - `-t`, `--test` Used to test the collection with an in-built sample specification - `-v`, `--version` Specifies the version of the converter - `-h`, `--help` Specifies all the options along with a few usage examples on the terminal ### Usage - Takes a specification (spec.yaml) as an input and writes to a file (collection.json) with pretty printing and using provided options ```terminal $ gql2postman -s spec.yaml -o collection.json -p -O depth=3,includeDeprecatedFields=true ``` - Takes a specification (spec.yaml) as an input and writes to a file (collection.json) with pretty printing and using provided options via config file ```terminal $ gql2postman -s spec.yaml -o collection.json -p -c ./examples/cli-options-config.json ``` - Takes a specification (spec.yaml) as an input and writes to a file (collection.json) with pretty printing and using provided options with larger depth limit to make sure more detailed and nested data is generated. ```terminal $ gql2postman -s spec.yaml -o collection.json -p -O depth=7,includeDeprecatedFields=true,optimizeConversion=false ``` - Testing the converter ```terminal $ gql2postman --test ``` ## 🛠 Using the converter as a NodeJS module In order to use the convert in your node application, you need to import the package using `require`. ```javascript var Converter = require('graphql-to-postman') ``` The converter provides the following functions: ### Convert The convert function takes in your GraphQL schema or SDL and converts it to a Postman collection. Signature: `convert (data, options, callback);` **data:** ```javascript { type: 'file', data: 'filepath' } OR { type: 'string', data: '' } ``` **options:** ```javascript { depth: 4, includeDeprecatedFields: false, optimizeConversion: false } /* All three properties are optional. Check the options section below for possible values for each option. */ ``` **callback:** ```javascript function (err, result) { /* result = { result: true, output: [ { type: 'collection', data: {..collection object..} } ] } */ } ``` ### Options - `depth` - The number of levels of information that should be returned. (A depth level of “1” returns that object and its properties. A depth of “2” will return all the nodes connected to the level 1 node, etc.) - `includeDeprecatedFields` - Generated queries will include deprecated fields or not. - `optimizeConversion` - Optimizes conversion for schemas with complex and nested input objects by reducing the depth to which input objects are resolved in GraphQL variables. ### ConversionResult - `result` - Flag responsible for providing a status whether the conversion was successful or not. - `reason` - Provides the reason for an unsuccessful conversion, defined only if result if `false`. - `output` - Contains an array of Postman objects, each one with a `type` and `data`. The only type currently supported is `collection`. ### Sample Usage ```javascript const fs = require('fs'), Converter = require('graphql-to-postman'), gqlData = fs.readFileSync('sample-spec.yaml', {encoding: 'UTF8'}); Converter.convert({ type: 'string', data: gqlData }, {}, (err, conversionResult) => { if (!conversionResult.result) { console.log('Could not convert', conversionResult.reason); } else { console.log('The collection object is: ', conversionResult.output[0].data); } } ); ``` ### Validate Function The validate function is meant to ensure that the data that is being passed to the [convert function](#convert-function) is a valid JSON object or a valid (YAML/JSON) string. The validate function is synchronous and returns a status object which conforms to the following schema #### Validation object schema ```javascript { type: 'object', properties: { result: { type: 'boolean'}, reason: { type: 'string' } }, required: ['result'] } ``` ##### Validation object explanation - `result` - true if the data is valid GraphQL and can be passed to the convert function - `reason` - Provides a reason for an unsuccessful validation of the specification --- _Source: https://npm.io/package/graphql-to-postman · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._