Skip to content

Commit 3d2c1ca

Browse files
VShingalaVShingala
authored
Merge pull request #629 from postmanlabs/feature/readme-update
Updated README.md with additional support that was added recently for OpenAPI 3.1 and Swagger 2.0 formats.
2 parents 9f78464 + b6f6a63 commit 3d2c1ca

File tree

1 file changed

+93
-88
lines changed

1 file changed

+93
-88
lines changed

‎README.md

Lines changed: 93 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
*Supercharge your API workflow.*
55
*Modern software is built on APIs. Postman helps you develop APIs faster.*
66

7-
# OpenAPI 3.0 to Postman Collection v2.1.0 Converter
7+
# OpenAPI 3.0, 3.1 and Swagger 2.0 to Postman Collection
88

99
![Build Status](https://github.com/postmanlabs/openapi-to-postman/actions/workflows/integration.yml/badge.svg)
1010

@@ -14,20 +14,26 @@
1414
#### Contents
1515

1616
1. [Getting Started](#getting-started)
17-
2. [Using the converter as a NodeJS module](#using-the-converter-as-a-nodejs-module)
17+
2. [Command Line Interface](#command-line-interface)
18+
1. [Options](#options)
19+
2. [Usage](#usage)
20+
3. [Using the converter as a NodeJS module](#using-the-converter-as-a-nodejs-module)
1821
1. [Convert Function](#convert)
1922
2. [Options](#options)
2023
3. [ConversionResult](#conversionresult)
2124
4. [Sample usage](#sample-usage)
2225
5. [Validate function](#validate-function)
23-
3. [Command Line Interface](#command-line-interface)
24-
1. [Options](#options)
25-
2. [Usage](#usage)
2626
4. [Conversion Schema](#conversion-schema)
2727

2828
---
2929

30-
## Getting Started
30+
---
31+
32+
### 🚀 We now also support OpenAPI 3.1 and Swagger 2.0 along with OpenAPI 3.0.
33+
---
34+
---
35+
36+
## 💭 Getting Started
3137

3238
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.
3339

@@ -41,7 +47,64 @@ If you want to use the converter in the CLI, install it globally with NPM:
4147
$ npm i -g openapi-to-postmanv2
4248
```
4349

44-
## Using the converter as a NodeJS module
50+
51+
## 📖 Command Line Interface
52+
53+
The converter can be used as a CLI tool as well. The following [command line options](#options) are available.
54+
55+
`openapi2postmanv2 [options]`
56+
57+
### Options
58+
59+
- `-s <source>`, `--spec <source>`
60+
Used to specify the OpenAPI specification (file path) which is to be converted
61+
62+
- `-o <destination>`, `--output <destination>`
63+
Used to specify the destination file in which the collection is to be written
64+
65+
- `-p`, `--pretty`
66+
Used to pretty print the collection object while writing to a file
67+
68+
- `-O`, `--options`
69+
Used to supply options to the converter, for complete options details see [here](/OPTIONS.md)
70+
71+
- `-c`, `--options-config`
72+
Used to supply options to the converter through config file, for complete options details see [here](/OPTIONS.md)
73+
74+
- `-t`, `--test`
75+
Used to test the collection with an in-built sample specification
76+
77+
- `-v`, `--version`
78+
Specifies the version of the converter
79+
80+
- `-h`, `--help`
81+
Specifies all the options along with a few usage examples on the terminal
82+
83+
84+
### Usage
85+
86+
- Takes a specification (spec.yaml) as an input and writes to a file (collection.json) with pretty printing and using provided options
87+
```terminal
88+
$ openapi2postmanv2 -s spec.yaml -o collection.json -p -O folderStrategy=Tags,includeAuthInfoInExample=false
89+
```
90+
91+
- 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
92+
```terminal
93+
$ openapi2postmanv2 -s spec.yaml -o collection.json -p -c ./examples/cli-options-config.json
94+
```
95+
96+
- Takes a specification (spec.yaml) as an input and writes to a file (collection.json) with pretty printing and using provided options (Also avoids any `"<Error: Too many levels of nesting to fake this schema>"` kind of errors present in converted collection)
97+
```terminal
98+
$ openapi2postmanv2 -s spec.yaml -o collection.json -p -O folderStrategy=Tags,requestParametersResolution=Example,optimizeConversion=false,stackLimit=50
99+
```
100+
101+
- Testing the converter
102+
```terminal
103+
$ openapi2postmanv2 --test
104+
```
105+
106+
107+
## 🛠 Using the converter as a NodeJS module
45108

46109
In order to use the convert in your node application, you need to import the package using `require`.
47110

@@ -53,7 +116,7 @@ The converter provides the following functions:
53116

54117
### Convert
55118

56-
The convert function takes in your OpenAPI specification ( YAML / JSON ) and converts it to a Postman collection.
119+
The convert function takes in your OpenAPI 3.0, 3.1 and Swagger 2.0 specification ( YAML / JSON ) and converts it to a Postman collection.
57120

58121
Signature: `convert (data, options, callback);`
59122

@@ -78,6 +141,7 @@ OR
78141
All three properties are optional. Check the options section below for possible values for each option.
79142
*/
80143
```
144+
Note: All possible values of options and their usage can be found over here: [OPTIONS.md](/OPTIONS.md)
81145

82146
**callback:**
83147
```javascript
@@ -96,26 +160,25 @@ function (err, result) {
96160
}
97161
```
98162

99-
### Options:
163+
### Options
100164

101165
Check out complete list of options and their usage at [OPTIONS.md](/OPTIONS.md)
102166

103167
### ConversionResult
104168

105-
- `result` - Flag responsible for providing a status whether the conversion was successful or not
169+
- `result` - Flag responsible for providing a status whether the conversion was successful or not.
106170

107-
- `reason` - Provides the reason for an unsuccessful conversion, defined only if result: false
171+
- `reason` - Provides the reason for an unsuccessful conversion, defined only if result if `false`.
108172

109173
- `output` - Contains an array of Postman objects, each one with a `type` and `data`. The only type currently supported is `collection`.
110174

111175

112176

113-
### Sample Usage:
177+
### Sample Usage
114178
```javascript
115-
var fs = require('fs'),
116-
117-
Converter = require('openapi-to-postmanv2'),
118-
openapiData = fs.readFileSync('sample-spec.yaml', {encoding: 'UTF8'});
179+
const fs = require('fs'),
180+
Converter = require('openapi-to-postmanv2'),
181+
openapiData = fs.readFileSync('sample-spec.yaml', {encoding: 'UTF8'});
119182

120183
Converter.convert({ type: 'string', data: openapiData },
121184
{}, (err, conversionResult) => {
@@ -153,77 +216,19 @@ The validate function is synchronous and returns a status object which conforms
153216

154217
- `reason` - Provides a reason for an unsuccessful validation of the specification
155218

219+
## 🧭 Conversion Schema
156220

157-
## Command Line Interface
158-
159-
The converter can be used as a CLI tool as well. The following [command line options](#options) are available.
160-
161-
`openapi2postmanv2 [options]`
162-
163-
### Options
164-
- `-v`, `--version`
165-
Specifies the version of the converter
166-
167-
- `-s <source>`, `--spec <source>`
168-
Used to specify the OpenAPI specification (file path) which is to be converted
169-
170-
- `-o <destination>`, `--output <destination>`
171-
Used to specify the destination file in which the collection is to be written
172-
173-
- `-t`, `--test`
174-
Used to test the collection with an in-built sample specification
175-
176-
- `-p`, `--pretty`
177-
Used to pretty print the collection object while writing to a file
178-
179-
- `-O`, `--options`
180-
Used to supply options to the converter, for complete options details see [here](/OPTIONS.md)
181-
182-
- `-c`, `--options-config`
183-
Used to supply options to the converter through config file, for complete options details see [here](/OPTIONS.md)
184-
185-
- `-h`, `--help`
186-
Specifies all the options along with a few usage examples on the terminal
187-
188-
189-
### Usage
190-
191-
**Sample usage examples of the converter CLI**
192-
193-
194-
- Takes a specification (spec.yaml) as an input and writes to a file (collection.json) with pretty printing and using provided options
195-
```terminal
196-
$ openapi2postmanv2 -s spec.yaml -o collection.json -p -O folderStrategy=Tags,includeAuthInfoInExample=false
197-
```
198-
199-
- 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
200-
```terminal
201-
$ openapi2postmanv2 -s spec.yaml -o collection.json -p -c ./examples/cli-options-config.json
202-
```
203-
204-
- Takes a specification (spec.yaml) as an input and writes to a file (collection.json) with pretty printing and using provided options (Also avoids any `"<Error: Too many levels of nesting to fake this schema>"` kind of errors present in converted collection)
205-
```terminal
206-
$ openapi2postmanv2 -s spec.yaml -o collection.json -p -O folderStrategy=Tags,requestParametersResolution=Example,optimizeConversion=false,stackLimit=50
207-
```
208-
209-
- Testing the converter
210-
```terminal
211-
$ openapi2postmanv2 --test
212-
```
213-
214-
## Conversion Schema
215-
216-
| *postman* | *openapi* | *options* | *examples* |
217-
| --- | --- | :---: | :--- |
218-
| collectionName | info.title | - | |
219-
| description | info.description + info.contact | - | |
220-
| collectionVariables| server.variables + pathVariables | - | |
221-
| folderName | paths.path | - | |
222-
| requestName | operationItem(method).operationId | default(operationId)-(`requestName`)enum['operationId','summary','url'] | |
223-
| request.method | path.method | - | |
221+
| *postman* | *openapi* | *related options* |
222+
| --- | --- | :---: |
223+
| collectionName | info.title | - |
224+
| description | info.description + info.contact | - |
225+
| collectionVariables| server.variables + pathVariables | - |
226+
| folderName | paths.path / tags.name | folderStrategy |
227+
| requestName | operationItem(method).summary / operationItem(method).operationId / url | requestNameSource |
228+
| request.method | path.method | - |
224229
| request.headers | parameter (`in = header`) | - | [link](#Header/Path-param-conversion-example) |
225-
| request.body | operationItem(method).requestBody | - | |
226-
| request.url.raw | server.url (path level server >> openapi server) + path | - | |
227-
| request.url.variables | parameter (`in = path`) | - | [link](#Header/Path-param-conversion-example) |
228-
| request.url.params | parameter (`in = query`) | - | {"key": param.name, "value": [link](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#style-examples)}|
229-
| api_key in (query or header) | components.securitySchemes.api_key | - ||
230+
| request.body | operationItem(method).requestBody | requestParametersResolution, exampleParametersResolution |
231+
| request.url.raw | server.url (path level server >> openapi server) + path | - |
232+
| request.url.variables | parameter (`in = path`) | - |
233+
| request.url.params | parameter (`in = query`) | - |
234+
| api_key in (query or header) | components.securitySchemes.api_key | includeAuthInfoInExample |

0 commit comments

Comments
 (0)