feat(tagging for redoc): add tagging for redoc

scripts/startdemoserver.ts

@@ -3,11 +3,12 @@ import * as smartexpress from '@pushrocks/smartexpress';
 import * as smartswagger from '../ts';
 
 const run = async () => {
-  const smartswaggerInstance = await smartswagger.Smartswagger.createFromUrl('https://my.sevdesk.de/OpenAPI/ReceiptAPI/openApi.json');
+  const smartswaggerInstance = await smartswagger.Smartswagger.createNew('A new OpenAPI Doc');
-  await smartswaggerInstance.mergeDocumentFromUrl('https://my.sevdesk.de/OpenAPI/ContactAPI/openApi.json', '');
+  await smartswaggerInstance.mergeDocumentFromUrl('https://my.sevdesk.de/OpenAPI/ReceiptAPI/openApi.json', '', 'Yes1');
-  await smartswaggerInstance.mergeDocumentFromUrl('https://my.sevdesk.de/OpenAPI/InvoiceAPI/openApi.json', '');
+  await smartswaggerInstance.mergeDocumentFromUrl('https://my.sevdesk.de/OpenAPI/ContactAPI/openApi.json', '', 'Yes2');
-  await smartswaggerInstance.mergeDocumentFromUrl('https://my.sevdesk.de/OpenAPI/OrderAPI/openApi.json', '');
+  await smartswaggerInstance.mergeDocumentFromUrl('https://my.sevdesk.de/OpenAPI/InvoiceAPI/openApi.json', '', 'Yes3');
-  await smartswaggerInstance.mergeDocumentFromUrl('https://my.sevdesk.de/OpenAPI/InventoryAPI/openApi.json', '');
+  await smartswaggerInstance.mergeDocumentFromUrl('https://my.sevdesk.de/OpenAPI/OrderAPI/openApi.json', '', 'Yes4');
+  await smartswaggerInstance.mergeDocumentFromUrl('https://my.sevdesk.de/OpenAPI/InventoryAPI/openApi.json', '', 'Yes5');
 
   // express stuff
   const expressServer = new smartexpress.Server({

ts/smartswagger.classes.smartswagger.ts

@@ -2,14 +2,14 @@ import path from 'path';
 import * as plugins from './smartswagger.plugins';
 
 interface RedocProps {
-  'x-tagGroups': any;
+  'x-tagGroups'?: {name: string, tags: string[]}[];
 }
 type IExtendedApiDoc = plugins.openapiTypes.OpenAPIV3.Document & RedocProps;
 
 export class Smartswagger {
   // STATIC
   /**
-   *
+   * creates a new Smartswagger instance from an external document
    * @param urlArg a url arg that contains an original swagger.json in the response
    * @returns an instance of
    */
@@ -24,6 +24,18 @@ export class Smartswagger {
     return newSMartswaggerInstance;
   }
 
+  public static async createNew(titleArg: string = 'an OpenApiDoc') {
+    const newSMartswaggerInstance = new Smartswagger({
+      openapi: '3.0.0',
+      paths: {},
+      info: {
+        title: titleArg,
+        version: '1.0.0'
+      }
+    });
+    return newSMartswaggerInstance;
+  }
+
   // INSTANCE
   /**
    * the basic info of the api doc
@@ -54,7 +66,7 @@ export class Smartswagger {
    * @param documentToMergeArg
    * @param basePathArg
    */
-  public async mergeDocument(documentToMergeArg: IExtendedApiDoc, basePathArg: string) {
+  public async mergeDocument(documentToMergeArg: IExtendedApiDoc, basePathArg: string = '', tagArg?: string) {
     console.log(`merging document with name ${documentToMergeArg.info?.title}`);
     await this.deref();
     // lets get a dereferenced version of the document we want to merge
@@ -65,6 +77,26 @@ export class Smartswagger {
       const pathToMerge = plugins.path.join(basePathArg, path);
       this.apiDoc.paths = this.apiDoc.paths || {};
       this.apiDoc.paths[pathToMerge] = documentToMerge.paths[path];
+      if (tagArg) {
+        if (this.apiDoc.paths[pathToMerge].post) {
+          this.apiDoc.paths[pathToMerge].post.tags = this.apiDoc.paths[pathToMerge].post.tags || [];
+          this.apiDoc.paths[pathToMerge].post.tags.push(tagArg);
+        }
+        if (this.apiDoc.paths[pathToMerge].get) {
+          this.apiDoc.paths[pathToMerge].get.tags = this.apiDoc.paths[pathToMerge].get.tags || [];
+          this.apiDoc.paths[pathToMerge].get.tags.push(tagArg);
+        }
+        if (this.apiDoc.paths[pathToMerge].put) {
+          this.apiDoc.paths[pathToMerge].put.tags = this.apiDoc.paths[pathToMerge].put.tags || [];
+          this.apiDoc.paths[pathToMerge].put.tags.push(tagArg);
+
+        }
+        if (this.apiDoc.paths[pathToMerge].delete) {
+          this.apiDoc.paths[pathToMerge].delete.tags = this.apiDoc.paths[pathToMerge].delete.tags || [];
+          this.apiDoc.paths[pathToMerge].delete.tags.push(tagArg);
+        }
+
+      }
     }
 
     // merge tag groups
@@ -75,12 +107,17 @@ export class Smartswagger {
       }
     }
     console.log('merged!');
+
+    // set custom tag arg.
+    if (tagArg) {
+      this.apiDoc['x-tagGroups'].push({name: tagArg, tags: [tagArg]});
+    }
   }
 
   /**
    * merges a document from url
    */
-  public async mergeDocumentFromUrl(documentUrlArg: string, basePathArg: string = '') {
+  public async mergeDocumentFromUrl(documentUrlArg: string, basePathArg: string = '', tagArg?: string) {
     console.log(`getting document at ${documentUrlArg} for merging...`);
     const documentResponse = await plugins.nodeFetch(documentUrlArg, {
       headers: {
@@ -90,17 +127,17 @@ export class Smartswagger {
     const documentString = await documentResponse.text();
     const apiDoc: IExtendedApiDoc = JSON.parse(documentString);
     console.log(`document successfully fetched!`);
-    await this.mergeDocument(apiDoc, basePathArg);
+    await this.mergeDocument(apiDoc, basePathArg, tagArg);
   }
 
   /**
    * merge multiple documents in parallel
    * @param urlArrayArg
    */
-  public async mergeManyDocumentsFromUrl(urlArrayArg: { url: string; basePath: string }[]) {
+  public async mergeManyDocumentsFromUrl(urlArrayArg: { url: string; basePath?: string, tagArg?: string }[]) {
     const promiseArray: Promise<void>[] = [];
     for (const urlArg of urlArrayArg) {
-      promiseArray.push(this.mergeDocumentFromUrl(urlArg.url, urlArg.basePath));
+      promiseArray.push(this.mergeDocumentFromUrl(urlArg.url, urlArg.basePath, urlArg.tagArg));
     }
     await Promise.all(promiseArray);
   }