feat: Use desc from folders for tags #53

Closes #53

Author: joolfe

docs/index.md

@@ -193,6 +193,8 @@ Have a look to the [SimplePost collection](https://github.com/joolfe/postman-to-
 
 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.
 
+As part of the implementation we now support `description` for [tags](https://swagger.io/specification/#tag-object), just add a description into the Postman Collection folder and automatically the `tags` section will be filled in the he OpenApi spec.
+
 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.
 
 ## Parameters parsing

lib/index.js

@@ -10,11 +10,13 @@ async function postmanToOpenApi (input, output, { info = {}, defaultTag = 'defau
   const { item: items } = postmanJson
   const paths = {}
   const domains = new Set()
+  const tags = {}
 
   for (let [i, element] of items.entries()) {
-    const { item, name } = element
+    const { item, name, description: tagDesc } = element
     if (item != null) { // is a folder
       const tagged = item.map(e => ({ ...e, tag: name }))
+      tags[name] = tagDesc
       items.splice(i, 1, ...tagged)
       element = tagged.shift()
     }
@@ -47,6 +49,7 @@ async function postmanToOpenApi (input, output, { info = {}, defaultTag = 'defau
     info: compileInfo(postmanJson, info),
     ...parseServers(domains, servers),
     ...parseAuth(postmanJson, auth),
+    ...parseTags(tags),
     paths
   }
 
@@ -254,4 +257,11 @@ function parseServers (domains, serversOpts) {
   return (servers.length > 0) ? { servers } : {}
 }
 
+/* Transform a object of tags in an array of tags */
+function parseTags (tagsObj) {
+  const tags = Object.entries(tagsObj)
+    .map(([name, description]) => ({ name, description }))
+  return (tags.length > 0) ? { tags } : {}
+}
+
 module.exports = postmanToOpenApi

test/resources/input/FolderCollection.json

@@ -1,6 +1,6 @@
 {
 	"info": {
-		"_postman_id": "3ad7e1b4-f3a1-4a8f-8bd0-56ff18f53339",
+		"_postman_id": "769a0782-149c-40f1-9532-74e2c116bb04",
 		"name": "Folder Collection",
 		"description": "Just a simple collection for test",
 		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
@@ -68,6 +68,29 @@
 					"response": []
 				}
 			],
+			"description": "Operations at User level",
+			"event": [
+				{
+					"listen": "prerequest",
+					"script": {
+						"id": "c69515db-ca18-4c49-b50f-421608912d3c",
+						"type": "text/javascript",
+						"exec": [
+							""
+						]
+					}
+				},
+				{
+					"listen": "test",
+					"script": {
+						"id": "d69a3a2c-1074-4318-9768-fdc958e03038",
+						"type": "text/javascript",
+						"exec": [
+							""
+						]
+					}
+				}
+			],
 			"protocolProfileBehavior": {}
 		},
 		{
@@ -102,6 +125,29 @@
 					"response": []
 				}
 			],
+			"description": "Operations for Post items",
+			"event": [
+				{
+					"listen": "prerequest",
+					"script": {
+						"id": "5d11f381-af50-45b2-8614-6a5bccfdb6d6",
+						"type": "text/javascript",
+						"exec": [
+							""
+						]
+					}
+				},
+				{
+					"listen": "test",
+					"script": {
+						"id": "7eed3e03-a385-45c2-9979-eeeba859623b",
+						"type": "text/javascript",
+						"exec": [
+							""
+						]
+					}
+				}
+			],
 			"protocolProfileBehavior": {}
 		},
 		{

test/resources/output/Folders.yml

@@ -5,6 +5,11 @@ info:
   version: 2.3.0
 servers:
   - url: 'https://api.io'
+tags:
+  - name: Users
+    description: Operations at User level
+  - name: Posts
+    description: Operations for Post items
 paths:
   /users:
     post: