Merge pull request #96 from joolfe/develop

nested folders feature

.gitignore

@@ -21,6 +21,7 @@ lib-cov
 
 # Coverage directory used by tools like istanbul
 coverage
+coverage/**
 *.lcov
 
 # nyc test coverage

CHANGELOG.md

@@ -1,3 +1,38 @@
+## [1.7.0](https://github.com/joolfe/postman-to-openapi/compare/1.6.1...1.7.0) (2021-03-28)
+
+
+### Features
+
+* add support for nested folders ([4f5ee97](https://github.com/joolfe/postman-to-openapi/commit/4f5ee97698c20898132329824acd72bdd00db1f3))
+* added concat and separator option to folder tags calculation ([4513095](https://github.com/joolfe/postman-to-openapi/commit/4513095a07d6e9f031d8e8bfaa18ea7d7c737701))
+* support empty folders Close [#89](https://github.com/joolfe/postman-to-openapi/issues/89) ([6397d7c](https://github.com/joolfe/postman-to-openapi/commit/6397d7c644e1d23e6dba989905af6089a927985c))
+
+
+### Bug Fixes
+
+* lint error fixes ([de025fd](https://github.com/joolfe/postman-to-openapi/commit/de025fdf977f2de42f16a0c2db1b448d8b4a4d49))
+* remove not needed code for feature ([48d7952](https://github.com/joolfe/postman-to-openapi/commit/48d7952df2685b9a95d54a6dc3b5b294bd708603))
+
+
+### Tests
+
+* add complex folder structure test ([56d00df](https://github.com/joolfe/postman-to-openapi/commit/56d00dfcf96543a3170f8382665be8108b291c94))
+
+
+### Documentation
+
+* update folder features ([83ae5bd](https://github.com/joolfe/postman-to-openapi/commit/83ae5bdaa89a2624deadac73c037f272263603f8))
+
+
+### Miscellaneous Chores
+
+* update version ([ebba3da](https://github.com/joolfe/postman-to-openapi/commit/ebba3da102bf05f00317dec5045ab32397fd07c7))
+
+
+### Build System
+
+* update deps ([42b0b96](https://github.com/joolfe/postman-to-openapi/commit/42b0b96d7949759c25fefeda8247dcd735028e16))
+
 ### [1.6.1](https://github.com/joolfe/postman-to-openapi/compare/1.6.0...1.6.1) (2021-03-14)
 
 

docs/index.md

@@ -15,7 +15,7 @@
 
 ## Features at a glance
 
-- Postman Collection v2.1 and v2.0
+- Postman Collection v2.1 and v2.0.
 - OpenApi 3.0
 - Basic info API from Postman info or customizable.
 - Basic method conversion (GET, POST, PUT...).
@@ -205,6 +205,62 @@ The info about the API external documentation, as described in OpenAPI spec [Ext
 
 This info can be provided as collection variables in the same way as described in section [License and Contact configuration](#license-and-contact-configuration), you can setup the variables `externalDocs.url` and `externalDocs.description` for provide the information.
 
+### folders (Object)
+
+This library support the use of folders and nested folders as OpenAPI `tags`, see [Folders as tags](#folders-as-tags) section for more info, with this options you can configure the behavior of the tags calculation when there exist multiple level of folders in the Postman collection, the fields inside `folders` object are:
+
+| Param            | Description                    |
+|------------------|--------------------------------|
+| `concat`         | Boolean. Indicated if in case of multiple levels of folders the tag used in the request is a concatenation of the folders name. Default value `true`. |
+| `separator`      | String. Separator used to concatenate the names of the different folders. Default value ` > ` |
+
+If we have a Postman collection with an structure as:
+
+```txt
+|- Domestic Payments (folder)
+    |- Consent (folder)
+        |- request 1
+    |- request 2
+|- Scheduled payments (folder)
+    |- Consent (folder)
+        |- request 3
+    |- request 4
+```
+
+The tags for each request would be:
+
+| Request   | Default config                 | Custom separator             | Avoid concatenation  |
+|-----------|--------------------------------|------------------------------|----------------------|
+| request 1 | `Domestic Payments > Consent`  | `Domestic Payments-Consent`  | `Consent`            |
+| request 2 | `Domestic Payments`            | `Domestic Payments`          | `Domestic Payments`  |
+| request 3 | `Scheduled payments > Consent` | `Scheduled payments-Consent` | `Consent`            |
+| request 4 | `Scheduled payments`           | `Scheduled payments`         | `Scheduled payments` |
+
+Default config:
+
+```js
+{
+    concat = true,
+    separator = ' > '
+}
+```
+
+Custom separator:
+
+```js
+{
+    separator = '-'
+}
+```
+
+Avoid concatenation
+
+```js
+{
+    concat = false
+}
+```
+
 </div></div>
 <div class="tilted-section"><div markdown="1">
 
@@ -230,7 +286,9 @@ Have a look to the [SimplePost collection](https://github.com/joolfe/postman-to-
 
 ## Folders as tags
 
-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](http://spec.openapis.org/oas/v3.0.3.html#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.
+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](http://spec.openapis.org/oas/v3.0.3.html#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.
+
+If you have more than one level of folders you can configure the behavior to calculate the tag of the request, See option [folders](#folders-object) for more info about how to configure this feature and some examples.
 
 As part of the implementation we now support `description` for [tags](http://spec.openapis.org/oas/v3.0.3.html#tag-object), just add a description into the Postman Collection folder and automatically the `tags` section will be filled in the he OpenApi spec.
 

lib/index.js

@@ -5,7 +5,10 @@ const { dump } = require('js-yaml')
 const { parseMdTable } = require('./md-utils')
 const { version } = require('../package.json')
 
-async function postmanToOpenApi (input, output, { info = {}, defaultTag = 'default', pathDepth = 0, auth, servers, externalDocs = {} } = {}) {
+async function postmanToOpenApi (input, output, {
+  info = {}, defaultTag = 'default', pathDepth = 0,
+  auth, servers, externalDocs = {}, folders = {}
+} = {}) {
   // TODO validate?
   const collectionFile = await readFile(input)
   const postmanJson = JSON.parse(collectionFile)
@@ -15,12 +18,14 @@ async function postmanToOpenApi (input, output, { info = {}, defaultTag = 'defau
   const tags = {}
 
   for (let [i, element] of items.entries()) {
-    const { item, name, description: tagDesc } = element
-    if (item != null) { // is a folder
-      const tagged = item.map(e => ({ ...e, tag: name }))
-      tags[name] = tagDesc
+    while (element.item != null) { // is a folder
+      const { item, description: tagDesc } = element
+      const tag = calculateFolderTag(element, folders)
+      const tagged = item.map(e => ({ ...e, tag }))
+      tags[tag] = tagDesc
       items.splice(i, 1, ...tagged)
-      element = tagged.shift()
+      // Empty folders will have tagged empty
+      element = (tagged.length > 0) ? tagged.shift() : items[i]
     }
     const {
       request: { url, method, body, description: rawDesc, header },
@@ -51,14 +56,18 @@ async function postmanToOpenApi (input, output, { info = {}, defaultTag = 'defau
     ...parseTags(tags),
     paths
   }
-
   const openApiYml = dump(openApi, { skipInvalid: true })
   if (output != null) {
     await writeFile(output, openApiYml, 'utf8')
   }
   return openApiYml
 }
 
+/* Calculate the tags for folders items based on the options */
+function calculateFolderTag ({ tag, name }, { separator = ' > ', concat = true }) {
+  return (tag && concat) ? `${tag}${separator}${name}` : name
+}
+
 function compileInfo (postmanJson, optsInfo) {
   const { info: { name, description: desc }, variable = [] } = postmanJson
   const ver = getVarValue(variable, 'version', '1.0.0')