You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Dec 27, 2024. It is now read-only.
* add nom badge ([1f5f407](https://github.com/joolfe/postman-to-openapi/commit/1f5f407f8eefcc18911522af5ee5e1b11f165426))
22
+
* added logo to the project ([60ef3cd](https://github.com/joolfe/postman-to-openapi/commit/60ef3cddd0e966a1f5d543aa92ffc9f9ddc12ab0))
23
+
* Features documentations [#52](https://github.com/joolfe/postman-to-openapi/issues/52) ([f91f60b](https://github.com/joolfe/postman-to-openapi/commit/f91f60b1bb5cb732490871e2becc937f84cb22fb))
24
+
* first structure ([505a03c](https://github.com/joolfe/postman-to-openapi/commit/505a03c854512cecb1af375d4bd5fea78cc2faa5))
25
+
* getting started ([dcb1cf7](https://github.com/joolfe/postman-to-openapi/commit/dcb1cf7885c9c40b4cc6a9da11563a87d24417ec)), closes [#47](https://github.com/joolfe/postman-to-openapi/issues/47)
🛸 Convert postman collection to OpenAPI specification.
6
6
7
7
Or in other words, transform [this specification](https://schema.getpostman.com/json/collection/v2.1.0/collection.json) to [this one](https://swagger.io/specification/)
🛸 Convert postman collection to OpenAPI specification, or in other words, transform [this specification](https://schema.getpostman.com/json/collection/v2.1.0/collection.json) to [this one](https://swagger.io/specification/)
|`inputPath`| String. Path of the Postman collection file. |
47
+
|`outputPath`| String. Path of the output file where the OpenAPi will be stored. This param is optional if not provided (`undefined` or `null`) no file will be saved. |
48
+
|`options`| Object. Optional configuration, see [options](#options) section for a detailed description. |
49
+
50
+
The method return a promise string that contain the yml OpenAPI specification, only is saved to a file if the `outputPath` parameter is provided.
The third parameter used in the library method is an `options` object containing the optional parameters for the transformation, the allowed parameters are:
83
+
84
+
### info (Object)
85
+
86
+
The basic information of the API is obtained from Postman collection as described in section [default info](#basic-api-info), but you can customize this parameters using the `info` options that can contain the next parameters:
|`version`| String. The version of the OpenAPI document. |
92
+
|`description`| String. A short description of the API. |
93
+
|`termsOfService`| String. A URL to the Terms of Service for the API. MUST be in the format of a URL. |
94
+
95
+
Basically this are the required and relevant parameters defined in OpenAPI spec [info object](https://swagger.io/specification/#info-object), an example of the option will be:
96
+
97
+
```js
98
+
{
99
+
info: {
100
+
title:'Options title',
101
+
version:'6.0.7-beta',
102
+
description:'Description from options',
103
+
termsOfService:'http://tos.myweb.com'
104
+
}
105
+
}
106
+
```
107
+
108
+
### defaultTag (String)
109
+
110
+
By default the [tag value](https://swagger.io/specification/#tag-object) "default" is added to all the operations during transformation, unless this operations are inside a folder as described in section [folder as tags](#folders-as-tags).
111
+
112
+
If you want to customize the default tag use the options `defaultTag` to indicate the desired value.
The global authorization info can be parse from the Postman collection as described in [Global authorization](#global-authorization) section, but you can customize this info using the `auth` option, this param is a Object that follow the structure of OpenAPI [Security Scheme](https://swagger.io/specification/#security-scheme-object), in this moment only type `http` is supported and schemes `basic` and `bearer`, as an example of this option:
121
+
122
+
```js
123
+
{
124
+
myCustomAuth: {
125
+
type:'http',
126
+
scheme:'bearer',
127
+
bearerFormat:'A resource owner JWT',
128
+
description:'My awesome authentication using bearer'
129
+
},
130
+
myCustomAuth2: {
131
+
type:'http',
132
+
scheme:'basic',
133
+
description:'My awesome authentication using user and password'
134
+
}
135
+
}
136
+
```
137
+
138
+
### servers (Array)
139
+
140
+
The global servers list can be parse from the Postman collection as described in [Global servers configuration](#global-servers-configuration) section, but you can customize this info using the `servers` option, this param is an array of objects that follow the structure of OpenAPI [Server Objects](https://swagger.io/specification/#server-object), only `url` and `description` field are supported in this moment, as an example of how to use this option:
141
+
142
+
```js
143
+
{
144
+
servers: [
145
+
{
146
+
url:'https://awesome.api.sandbox.io',
147
+
description:'Sandbox environment server'
148
+
},
149
+
{
150
+
url:'https://awesome.api.io',
151
+
description:'Production environment server'
152
+
}
153
+
]
154
+
}
155
+
```
156
+
49
157
</div></div>
50
158
<divclass="tilted-section"><divmarkdown="1">
51
159
52
160
# Features
53
161
162
+
## Basic conversion
163
+
164
+
This library support the transformation from Postman collection to all the basic HTTP method as GET, POST, PUT... and also parse the body request of type raw `Json` or `Text` type. [Query parameters](#parameters-parsing) are also supported.
165
+
166
+
Have a look to the [PostmantoOpenAPI collection](https://github.com/joolfe/postman-to-openapi/blob/master/test/resources/input/PostmantoOpenAPI.json) file for an example of how to use this feature.
167
+
168
+
## Basic API info
169
+
170
+
For fill the OpenAPI [info object](https://swagger.io/specification/#info-object) this library use the information defined in Postman [collection](https://learning.postman.com/docs/sending-requests/intro-to-collections/#creating-collections) level as "name" and "description".
171
+
172
+
Postman don't have any field at collection level that feat with OpenAPI "version" field (is a required field in OpenAPI specification), so this library look for a variable with name `version` in Postman [collection variables](https://learning.postman.com/docs/sending-requests/variables/#defining-collection-variables) or if variable is not defined then will use the default value `1.0.0`.
173
+
174
+
You can customize all this information with the [Info option](#info-(object)).
175
+
176
+
Have a look to the [SimplePost collection](https://github.com/joolfe/postman-to-openapi/blob/master/test/resources/input/SimplePost.json) file for an example of how to use this feature.
177
+
178
+
## Folders as tags
179
+
180
+
In postman you can add [folders](https://learning.postman.com/docs/sending-requests/intro-to-collections/) inside your collection to group requests and keep the collection clean, in OpenAPI there are no folders but exist the concept of [tags](https://swagger.io/specification/#tag-object) that has the same approximate meaning, this library automatically detect folders and use the name of the folder as tag name in the transformation. Right now is not possible to have more than one tag value for each operation.
181
+
182
+
Have a look to the [FolderCollection](https://github.com/joolfe/postman-to-openapi/blob/master/test/resources/input/FolderCollection.json) file for an example of how to use this feature.
183
+
184
+
## Parameters parsing
185
+
186
+
This library automatically transform query and headers parameters from Postman operations tp OpenAPI specification, the populated info is the name, description and use the value of the parameter as an example.
187
+
188
+
The default schema used for parameters is `string` but the library try to infer the type of the parameters based on the value using regular expressions, the detected types are `integer`, `number`, `boolean` and `string`, if you find any problem in the inference process please open an issue.
189
+
190
+
Path parameters are also automatically detected, this library look for [Postman variables](https://learning.postman.com/docs/sending-requests/variables/) in the url as `{{variable}}` and transform to a single curly brace expression as `{variable}` as supported by OpenAPI, also create the parameter definition using the variable name.
191
+
192
+
Have a look to the [GetMethods collection](https://github.com/joolfe/postman-to-openapi/blob/master/test/resources/input/GetMethods.json), [Headers collection](https://github.com/joolfe/postman-to-openapi/blob/master/test/resources/input/Headers.json) and [PathParams collection](https://github.com/joolfe/postman-to-openapi/blob/master/test/resources/input/PathParams.json) files for examples of how to use this features.
193
+
194
+
## Global authorization
195
+
196
+
The OpenAPI root [security]https://swagger.io/specification/#openapi-object) definition is filled using the authorization method defined at Postman Collection [authorization config](https://learning.postman.com/docs/sending-requests/authorization/#inheriting-auth).
197
+
198
+
Only types 'Basic Auth' and 'Bearer Token' are supported now and not operation individual definition is supported.
199
+
200
+
You can customize the global authorization definition using the [Auth option](#auth-(object)).
201
+
202
+
Have a look to the collections [AuthBasic](https://github.com/joolfe/postman-to-openapi/blob/master/test/resources/input/AuthBasic.json) and [AuthBearer](https://github.com/joolfe/postman-to-openapi/blob/master/test/resources/input/AuthBearer.json) for examples of how to use this feature.
203
+
204
+
## Global servers configuration
205
+
206
+
The OpenAPI root [servers](https://swagger.io/specification/#openapi-object) definition is filled parsing the urls used in the Postman collections requests, the library use all the different urls for create an array of server (removing duplicated), but normally this is not to usefully as Postman collection only will have one environment url, for this reason you can customize the global servers definition using the [server option](#servers-(array))
207
+
208
+
If you don't want to include a `servers` array in your OpenAPI spec file you just need to pass an empty array as server option, as for example:
0 commit comments