Skip to content

Commit c8b903b

Browse files
VShingalaVShingala
committed
Added support for maximum depth and CLI usage
1 parent ea80b8d commit c8b903b

File tree

6 files changed

+4699
-28
lines changed

6 files changed

+4699
-28
lines changed

‎README.md

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,226 @@ _Manage all of your organization's APIs in Postman, with the industry's most com
88
# graphql-to-postman [![Build Status](https://travis-ci.com/postmanlabs/graphql-to-postman.svg?branch=master)](https://travis-ci.com/postmanlabs/graphql-to-postman)
99

1010
This module can be used to convert a GraphQL schema into a [Postman Collection V2](https://github.com/postmanlabs/postman-collection) format.
11+
12+
13+
14+
<img src="https://voyager.postman.com/logo/postman-logo-orange.svg" width="320" alt="The Postman Logo">
15+
16+
*Supercharge your API workflow.*
17+
*Modern software is built on APIs. Postman helps you develop APIs faster.*
18+
19+
# GraphQL to Postman Collection
20+
21+
![Build Status](https://github.com/postmanlabs/graphql-to-postman/actions/workflows/test.yml/badge.svg)
22+
23+
<a href="https://www.npmjs.com/package/graphql-to-postman" alt="Latest Stable Version">![npm](https://img.shields.io/npm/v/graphql-to-postman.svg)</a>
24+
<a href="https://www.npmjs.com/package/graphql-to-postman" alt="Total Downloads">![npm](https://img.shields.io/npm/dw/graphql-to-postman.svg)</a>
25+
26+
#### Contents
27+
28+
1. [Getting Started](#getting-started)
29+
2. [Command Line Interface](#command-line-interface)
30+
1. [Options](#options)
31+
2. [Usage](#usage)
32+
3. [Using the converter as a NodeJS module](#using-the-converter-as-a-nodejs-module)
33+
1. [Convert Function](#convert)
34+
2. [Options](#options)
35+
3. [ConversionResult](#conversionresult)
36+
4. [Sample usage](#sample-usage)
37+
5. [Validate function](#validate-function)
38+
4. [Conversion Schema](#conversion-schema)
39+
40+
---
41+
42+
---
43+
44+
45+
## 💭 Getting Started
46+
47+
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.
48+
49+
```terminal
50+
$ npm install graphql-to-postman
51+
```
52+
53+
If you want to use the converter in the CLI, install it globally with NPM:
54+
55+
```terminal
56+
$ npm i -g graphql-to-postman
57+
```
58+
59+
60+
## 📖 Command Line Interface
61+
62+
The converter can be used as a CLI tool as well. The following [command line options](#options) are available.
63+
64+
`gql2postman [options]`
65+
66+
### Options
67+
68+
- `-s <source>`, `--spec <source>`
69+
Used to specify the GraphQL specification (file path) which is to be converted
70+
71+
- `-o <destination>`, `--output <destination>`
72+
Used to specify the destination file in which the collection is to be written
73+
74+
- `-p`, `--pretty`
75+
Used to pretty print the collection object while writing to a file
76+
77+
- `-i`, `--interface-version`
78+
Specifies the interface version of the converter to be used. Value can be 'v2' or 'v1'. Default is 'v2'.
79+
80+
- `-O`, `--options`
81+
Used to supply options to the converter, for complete options details see [here](/OPTIONS.md)
82+
83+
- `-c`, `--options-config`
84+
Used to supply options to the converter through config file, for complete options details see [here](/OPTIONS.md)
85+
86+
- `-t`, `--test`
87+
Used to test the collection with an in-built sample specification
88+
89+
- `-v`, `--version`
90+
Specifies the version of the converter
91+
92+
- `-h`, `--help`
93+
Specifies all the options along with a few usage examples on the terminal
94+
95+
96+
### Usage
97+
98+
- Takes a specification (spec.yaml) as an input and writes to a file (collection.json) with pretty printing and using provided options
99+
```terminal
100+
$ gql2postman -s spec.yaml -o collection.json -p -O depth=3,includeDeprecatedFields=true
101+
```
102+
103+
- 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
104+
```terminal
105+
$ gql2postman -s spec.yaml -o collection.json -p -c ./examples/cli-options-config.json
106+
```
107+
108+
- 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
109+
to make sure more detailed and nested data is generated.
110+
```terminal
111+
$ gql2postman -s spec.yaml -o collection.json -p -O depth=7,includeDeprecatedFields=true,optimizeConversion=false
112+
```
113+
114+
- Testing the converter
115+
```terminal
116+
$ gql2postman --test
117+
```
118+
119+
120+
## 🛠 Using the converter as a NodeJS module
121+
122+
In order to use the convert in your node application, you need to import the package using `require`.
123+
124+
```javascript
125+
var Converter = require('graphql-to-postman')
126+
```
127+
128+
The converter provides the following functions:
129+
130+
### Convert
131+
132+
The convert function takes in your GraphQL schema or SDL and converts it to a Postman collection.
133+
134+
Signature: `convert (data, options, callback);`
135+
136+
**data:**
137+
138+
```javascript
139+
{ type: 'file', data: 'filepath' }
140+
OR
141+
{ type: 'string', data: '<entire GraphQL string - schema or SDL>' }
142+
```
143+
144+
**options:**
145+
```javascript
146+
{
147+
depth: 4,
148+
includeDeprecatedFields: false,
149+
optimizeConversion: false
150+
}
151+
/*
152+
All three properties are optional. Check the options section below for possible values for each option.
153+
*/
154+
```
155+
156+
**callback:**
157+
```javascript
158+
function (err, result) {
159+
/*
160+
result = {
161+
result: true,
162+
output: [
163+
{
164+
type: 'collection',
165+
data: {..collection object..}
166+
}
167+
]
168+
}
169+
*/
170+
}
171+
```
172+
173+
### Options
174+
175+
- `depth` - The number of levels of information that should be returned. (A depth level of “1” returns that object and
176+
its properties. A depth of “2” will return all the nodes connected to the level 1 node, etc.)
177+
178+
- `includeDeprecatedFields` - Generated queries will include deprecated fields or not.
179+
180+
- `optimizeConversion` - Optimizes conversion for schemas with complex and nested input objects by reducing the depth to
181+
which input objects are resolved in GraphQL variables.
182+
183+
### ConversionResult
184+
185+
- `result` - Flag responsible for providing a status whether the conversion was successful or not.
186+
187+
- `reason` - Provides the reason for an unsuccessful conversion, defined only if result if `false`.
188+
189+
- `output` - Contains an array of Postman objects, each one with a `type` and `data`. The only type currently supported is `collection`.
190+
191+
192+
193+
### Sample Usage
194+
```javascript
195+
const fs = require('fs'),
196+
Converter = require('graphql-to-postman'),
197+
gqlData = fs.readFileSync('sample-spec.yaml', {encoding: 'UTF8'});
198+
199+
Converter.convert({ type: 'string', data: gqlData },
200+
{}, (err, conversionResult) => {
201+
if (!conversionResult.result) {
202+
console.log('Could not convert', conversionResult.reason);
203+
}
204+
else {
205+
console.log('The collection object is: ', conversionResult.output[0].data);
206+
}
207+
}
208+
);
209+
```
210+
211+
### Validate Function
212+
213+
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.
214+
215+
The validate function is synchronous and returns a status object which conforms to the following schema
216+
217+
#### Validation object schema
218+
219+
```javascript
220+
{
221+
type: 'object',
222+
properties: {
223+
result: { type: 'boolean'},
224+
reason: { type: 'string' }
225+
},
226+
required: ['result']
227+
}
228+
```
229+
230+
##### Validation object explanation
231+
- `result` - true if the data is valid GraphQL and can be passed to the convert function
232+
233+
- `reason` - Provides a reason for an unsuccessful validation of the specification

0 commit comments

Comments
 (0)