graphql-to-postman
v0.3.0
Published
Generates a Postman Collection from a GraphQL schema.
Downloads
14,028
Readme
Supercharge your API workflow. Modern software is built on APIs. Postman helps you develop APIs faster.
GraphQL to Postman Collection
Contents
💭 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.
$ npm install graphql-to-postman
If you want to use the converter in the CLI, install it globally with NPM:
$ 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 are available.
gql2postman [options]
Options
-s <source>
,--spec <source>
Used to specify the GraphQL specification (file path) which is to be converted-o <destination>
,--output <destination>
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-c
,--options-config
Used to supply options to the converter through config file, for complete options details see here-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
$ 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
$ 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.
$ gql2postman -s spec.yaml -o collection.json -p -O depth=7,includeDeprecatedFields=true,optimizeConversion=false
- Testing the converter
$ 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
.
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:
{ type: 'file', data: 'filepath' }
OR
{ type: 'string', data: '<entire GraphQL string - schema or SDL>' }
options:
{
depth: 4,
includeDeprecatedFields: false,
optimizeConversion: false
}
/*
All three properties are optional. Check the options section below for possible values for each option.
*/
callback:
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 iffalse
.output
- Contains an array of Postman objects, each one with atype
anddata
. The only type currently supported iscollection
.
Sample Usage
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 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
{
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 functionreason
- Provides a reason for an unsuccessful validation of the specification