docusaurus-plugin-openapi-docs 0.0.0-699 → 0.0.0-700

package/lib/index.js

@@ -92,7 +92,7 @@ function pluginOpenAPIDocs(context, options) {
             : path_1.default.resolve(siteDir, specPath);
         try {
             const openapiFiles = await (0, openapi_1.readOpenapiFiles)(contentPath);
-            const [loadedApi, tags] = await (0, openapi_1.processOpenapiFiles)(openapiFiles, options, sidebarOptions);
+            const [loadedApi, tags, tagGroups] = await (0, openapi_1.processOpenapiFiles)(openapiFiles, options, sidebarOptions);
             if (!fs_1.default.existsSync(outputDir)) {
                 try {
                     fs_1.default.mkdirSync(outputDir, { recursive: true });
@@ -104,7 +104,7 @@ function pluginOpenAPIDocs(context, options) {
             }
             // TODO: figure out better way to set default
             if (Object.keys(sidebarOptions !== null && sidebarOptions !== void 0 ? sidebarOptions : {}).length > 0) {
-                const sidebarSlice = (0, sidebars_1.default)(sidebarOptions, options, loadedApi, tags, docPath);
+                const sidebarSlice = (0, sidebars_1.default)(sidebarOptions, options, loadedApi, tags, docPath, tagGroups);
                 const sidebarSliceTemplate = `module.exports = {{{slice}}};`;
                 const view = (0, mustache_1.render)(sidebarSliceTemplate, {
                     slice: JSON.stringify(sidebarSlice),

package/lib/openapi/openapi.d.ts

@@ -1,12 +1,12 @@
 import { ApiMetadata, APIOptions, SidebarOptions } from "../types";
-import { OpenApiObject, TagObject } from "./types";
+import { OpenApiObject, TagGroupObject, TagObject } from "./types";
 interface OpenApiFiles {
     source: string;
     sourceDirName: string;
     data: OpenApiObject;
 }
 export declare function readOpenapiFiles(openapiPath: string): Promise<OpenApiFiles[]>;
-export declare function processOpenapiFiles(files: OpenApiFiles[], options: APIOptions, sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[][]]>;
-export declare function processOpenapiFile(openapiData: OpenApiObject, options: APIOptions, sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[]]>;
+export declare function processOpenapiFiles(files: OpenApiFiles[], options: APIOptions, sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[][], TagGroupObject[]]>;
+export declare function processOpenapiFile(openapiData: OpenApiObject, options: APIOptions, sidebarOptions: SidebarOptions): Promise<[ApiMetadata[], TagObject[], TagGroupObject[]]>;
 export declare function getTagDisplayName(tagName: string, tags: TagObject[]): string;
 export {};

package/lib/openapi/openapi.js

@@ -461,7 +461,8 @@ async function processOpenapiFiles(files, options, sidebarOptions) {
                 ...item,
             }));
             const tags = processedFile[1];
-            return [itemsObjectsArray, tags];
+            const tagGroups = processedFile[2];
+            return [itemsObjectsArray, tags, tagGroups];
         }
         console.warn(chalk_1.default.yellow(`WARNING: the following OpenAPI spec returned undefined: ${file.source}`));
         return [];
@@ -484,7 +485,20 @@ async function processOpenapiFiles(files, options, sidebarOptions) {
         // Remove undefined tags due to transient parsing errors
         return x !== undefined;
     });
-    return [items, tags];
+    const tagGroups = metadata
+        .map(function (x) {
+        return x[2];
+    })
+        .flat()
+        .filter(function (x) {
+        // Remove undefined tags due to transient parsing errors
+        return x !== undefined;
+    });
+    return [
+        items,
+        tags,
+        tagGroups,
+    ];
 }
 exports.processOpenapiFiles = processOpenapiFiles;
 async function processOpenapiFile(openapiData, options, sidebarOptions) {
@@ -495,7 +509,11 @@ async function processOpenapiFile(openapiData, options, sidebarOptions) {
     if (openapiData.tags !== undefined) {
         tags = openapiData.tags;
     }
-    return [items, tags];
+    let tagGroups = [];
+    if (openapiData["x-tagGroups"] !== undefined) {
+        tagGroups = openapiData["x-tagGroups"];
+    }
+    return [items, tags, tagGroups];
 }
 exports.processOpenapiFile = processOpenapiFile;
 // order for picking items as a display name of tags

package/lib/openapi/openapi.test.js

@@ -24,6 +24,8 @@ describe("openapi", () => {
             const yaml = results.find((x) => x.source.endsWith("openapi.yaml"));
             expect(yaml).toBeTruthy();
             expect(yaml === null || yaml === void 0 ? void 0 : yaml.sourceDirName).toBe(".");
+            expect(yaml === null || yaml === void 0 ? void 0 : yaml.data.tags).toBeDefined();
+            expect(yaml === null || yaml === void 0 ? void 0 : yaml.data["x-tagGroups"]).toBeDefined();
         });
     });
 });

package/lib/openapi/types.d.ts

@@ -13,6 +13,7 @@ export interface OpenApiObject {
     externalDocs?: ExternalDocumentationObject;
     swagger?: string;
     "x-webhooks"?: PathsObject;
+    "x-tagGroups"?: TagGroupObject[];
 }
 export interface OpenApiObjectWithRef {
     openapi: string;
@@ -252,6 +253,10 @@ export interface TagObject {
     externalDocs?: ExternalDocumentationObject;
     "x-displayName"?: string;
 }
+export interface TagGroupObject {
+    name: string;
+    tags: string[];
+}
 export interface ReferenceObject {
     $ref: string;
 }

package/lib/options.js

@@ -9,7 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OptionsSchema = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
 const sidebarOptions = utils_validation_1.Joi.object({
-    groupPathsBy: utils_validation_1.Joi.string().valid("tag"),
+    groupPathsBy: utils_validation_1.Joi.string().valid("tag", "tagGroup"),
     categoryLinkSource: utils_validation_1.Joi.string().valid("tag", "info", "auto"),
     customProps: utils_validation_1.Joi.object(),
     sidebarCollapsible: utils_validation_1.Joi.boolean(),

package/lib/sidebars/index.d.ts

@@ -1,4 +1,4 @@
 import { ProcessedSidebar } from "@docusaurus/plugin-content-docs/src/sidebars/types";
-import { TagObject } from "../openapi/types";
+import { TagGroupObject, TagObject } from "../openapi/types";
 import type { SidebarOptions, APIOptions, ApiMetadata } from "../types";
-export default function generateSidebarSlice(sidebarOptions: SidebarOptions, options: APIOptions, api: ApiMetadata[], tags: TagObject[][], docPath: string): ProcessedSidebar;
+export default function generateSidebarSlice(sidebarOptions: SidebarOptions, options: APIOptions, api: ApiMetadata[], tags: TagObject[][], docPath: string, tagGroups?: TagGroupObject[]): ProcessedSidebar;

package/lib/sidebars/index.js

@@ -52,7 +52,7 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
             apiTags.push(tag.name);
         }
     });
-    apiTags = (0, uniq_1.default)(apiTags.concat(operationTags));
+    // apiTags = uniq(apiTags.concat(operationTags));
     const basePath = docPath
         ? outputDir.split(docPath)[1].replace(/^\/+/g, "")
         : outputDir.slice(outputDir.indexOf("/", 1)).replace(/^\/+/g, "");
@@ -175,9 +175,28 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
     }
     return [...tagged, ...untagged, ...schemas];
 }
-function generateSidebarSlice(sidebarOptions, options, api, tags, docPath) {
+function generateSidebarSlice(sidebarOptions, options, api, tags, docPath, tagGroups) {
     let sidebarSlice = [];
-    if (sidebarOptions.groupPathsBy === "tag") {
+    if (sidebarOptions.groupPathsBy === "tagGroup") {
+        tagGroups === null || tagGroups === void 0 ? void 0 : tagGroups.forEach((tagGroup) => {
+            //filter tags only included in group
+            const filteredTags = [];
+            tags[0].forEach((tag) => {
+                if (tagGroup.tags.includes(tag.name)) {
+                    filteredTags.push(tag);
+                }
+            });
+            const groupCategory = {
+                type: "category",
+                label: tagGroup.name,
+                collapsible: true,
+                collapsed: true,
+                items: groupByTags(api, sidebarOptions, options, [filteredTags], docPath),
+            };
+            sidebarSlice.push(groupCategory);
+        });
+    }
+    else if (sidebarOptions.groupPathsBy === "tag") {
         sidebarSlice = groupByTags(api, sidebarOptions, options, tags, docPath);
     }
     return sidebarSlice;

package/lib/types.d.ts

@@ -107,6 +107,12 @@ export interface SchemaPageMetadata extends ApiMetadataBase {
     schema: SchemaObject;
     markdown?: string;
 }
+export interface TagGroupPageMetadata extends ApiMetadataBase {
+    type: "tagGroup";
+    name: string;
+    tags: TagObject[];
+    markdown?: string;
+}
 export declare type ApiInfo = InfoObject;
 export interface ApiNavLink {
     title: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-699",
+  "version": "0.0.0-700",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -60,5 +60,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "ef318267f54c34bedf50f0b309c9bb30fd665b53"
+  "gitHead": "309ea5d0c101d526975380a13915decebca3e86b"
 }

package/src/index.ts

@@ -131,7 +131,7 @@ export default function pluginOpenAPIDocs(
 
     try {
       const openapiFiles = await readOpenapiFiles(contentPath);
-      const [loadedApi, tags] = await processOpenapiFiles(
+      const [loadedApi, tags, tagGroups] = await processOpenapiFiles(
         openapiFiles,
         options,
         sidebarOptions!
@@ -155,7 +155,8 @@ export default function pluginOpenAPIDocs(
           options,
           loadedApi,
           tags,
-          docPath
+          docPath,
+          tagGroups
         );
 
         const sidebarSliceTemplate = `module.exports = {{{slice}}};`;

package/src/openapi/__fixtures__/examples/openapi.yaml

@@ -11,3 +11,32 @@ paths:
       responses:
         200:
           description: OK
+
+tags:
+  - name: tag1
+    description: Everything about your Pets
+    x-displayName: Tag 1
+  - name: tag2
+    description: Tag 2 description
+    x-displayName: Tag 2
+  - name: tag3
+    description: Tag 3 description
+    x-displayName: Tag 3
+  - name: tag4
+    description: Tag 4 description
+    x-displayName: Tag 4
+
+x-tagGroups:
+  - name: Tag 1 & 2
+    tags:
+      - tag1
+      - tag2
+  - name: Trinity
+    tags:
+      - tag1
+      - tag2
+      - tag3
+  - name: Last Two
+    tags:
+      - tag3
+      - tag4

package/src/openapi/openapi.test.ts

@@ -28,6 +28,9 @@ describe("openapi", () => {
       const yaml = results.find((x) => x.source.endsWith("openapi.yaml"));
       expect(yaml).toBeTruthy();
       expect(yaml?.sourceDirName).toBe(".");
+
+      expect(yaml?.data.tags).toBeDefined();
+      expect(yaml?.data["x-tagGroups"]).toBeDefined();
     });
   });
 });

package/src/openapi/openapi.ts

@@ -29,7 +29,7 @@ import {
   TagPageMetadata,
 } from "../types";
 import { sampleRequestFromSchema } from "./createRequestExample";
-import { OpenApiObject, TagObject } from "./types";
+import { OpenApiObject, TagGroupObject, TagObject } from "./types";
 import { loadAndResolveSpec } from "./utils/loadAndResolveSpec";
 
 /**
@@ -579,7 +579,7 @@ export async function processOpenapiFiles(
   files: OpenApiFiles[],
   options: APIOptions,
   sidebarOptions: SidebarOptions
-): Promise<[ApiMetadata[], TagObject[][]]> {
+): Promise<[ApiMetadata[], TagObject[][], TagGroupObject[]]> {
   const promises = files.map(async (file) => {
     if (file.data !== undefined) {
       const processedFile = await processOpenapiFile(
@@ -591,7 +591,8 @@ export async function processOpenapiFiles(
         ...item,
       }));
       const tags = processedFile[1];
-      return [itemsObjectsArray, tags];
+      const tagGroups = processedFile[2];
+      return [itemsObjectsArray, tags, tagGroups];
     }
     console.warn(
       chalk.yellow(
@@ -610,6 +611,7 @@ export async function processOpenapiFiles(
       // Remove undefined items due to transient parsing errors
       return x !== undefined;
     });
+
   const tags = metadata
     .map(function (x) {
       return x[1];
@@ -618,14 +620,29 @@ export async function processOpenapiFiles(
       // Remove undefined tags due to transient parsing errors
       return x !== undefined;
     });
-  return [items as ApiMetadata[], tags as TagObject[][]];
+
+  const tagGroups = metadata
+    .map(function (x) {
+      return x[2];
+    })
+    .flat()
+    .filter(function (x) {
+      // Remove undefined tags due to transient parsing errors
+      return x !== undefined;
+    });
+
+  return [
+    items as ApiMetadata[],
+    tags as TagObject[][],
+    tagGroups as TagGroupObject[],
+  ];
 }
 
 export async function processOpenapiFile(
   openapiData: OpenApiObject,
   options: APIOptions,
   sidebarOptions: SidebarOptions
-): Promise<[ApiMetadata[], TagObject[]]> {
+): Promise<[ApiMetadata[], TagObject[], TagGroupObject[]]> {
   const postmanCollection = await createPostmanCollection(openapiData);
   const items = createItems(openapiData, options, sidebarOptions);
 
@@ -635,7 +652,13 @@ export async function processOpenapiFile(
   if (openapiData.tags !== undefined) {
     tags = openapiData.tags;
   }
-  return [items, tags];
+
+  let tagGroups: TagGroupObject[] = [];
+  if (openapiData["x-tagGroups"] !== undefined) {
+    tagGroups = openapiData["x-tagGroups"];
+  }
+
+  return [items, tags, tagGroups];
 }
 
 // order for picking items as a display name of tags

package/src/openapi/types.ts

@@ -22,6 +22,7 @@ export interface OpenApiObject {
   externalDocs?: ExternalDocumentationObject;
   swagger?: string;
   "x-webhooks"?: PathsObject;
+  "x-tagGroups"?: TagGroupObject[];
 }
 
 export interface OpenApiObjectWithRef {
@@ -311,6 +312,11 @@ export interface TagObject {
   "x-displayName"?: string;
 }
 
+export interface TagGroupObject {
+  name: string;
+  tags: string[];
+}
+
 export interface ReferenceObject {
   $ref: string;
 }

package/src/options.ts

@@ -8,7 +8,7 @@
 import { Joi } from "@docusaurus/utils-validation";
 
 const sidebarOptions = Joi.object({
-  groupPathsBy: Joi.string().valid("tag"),
+  groupPathsBy: Joi.string().valid("tag", "tagGroup"),
   categoryLinkSource: Joi.string().valid("tag", "info", "auto"),
   customProps: Joi.object(),
   sidebarCollapsible: Joi.boolean(),

package/src/sidebars/index.ts

@@ -7,6 +7,7 @@
 
 import path from "path";
 
+import { ProcessedSidebarItem } from "@docusaurus/plugin-content-docs/lib/sidebars/types";
 import {
   ProcessedSidebar,
   SidebarItemCategory,
@@ -18,7 +19,7 @@ import clsx from "clsx";
 import { kebabCase } from "lodash";
 import uniq from "lodash/uniq";
 
-import { TagObject } from "../openapi/types";
+import { TagGroupObject, TagObject } from "../openapi/types";
 import type {
   SidebarOptions,
   APIOptions,
@@ -86,7 +87,7 @@ function groupByTags(
       apiTags.push(tag.name!);
     }
   });
-  apiTags = uniq(apiTags.concat(operationTags));
+  // apiTags = uniq(apiTags.concat(operationTags));
 
   const basePath = docPath
     ? outputDir.split(docPath!)[1].replace(/^\/+/g, "")
@@ -241,11 +242,38 @@ export default function generateSidebarSlice(
   options: APIOptions,
   api: ApiMetadata[],
   tags: TagObject[][],
-  docPath: string
+  docPath: string,
+  tagGroups?: TagGroupObject[]
 ) {
   let sidebarSlice: ProcessedSidebar = [];
 
-  if (sidebarOptions.groupPathsBy === "tag") {
+  if (sidebarOptions.groupPathsBy === "tagGroup") {
+    tagGroups?.forEach((tagGroup) => {
+      //filter tags only included in group
+      const filteredTags: TagObject[] = [];
+      tags[0].forEach((tag) => {
+        if (tagGroup.tags.includes(tag.name as string)) {
+          filteredTags.push(tag);
+        }
+      });
+
+      const groupCategory = {
+        type: "category" as const,
+        label: tagGroup.name,
+        collapsible: true,
+        collapsed: true,
+        items: groupByTags(
+          api as ApiPageMetadata[],
+          sidebarOptions,
+          options,
+          [filteredTags],
+          docPath
+        ),
+      } as ProcessedSidebarItem;
+
+      sidebarSlice.push(groupCategory);
+    });
+  } else if (sidebarOptions.groupPathsBy === "tag") {
     sidebarSlice = groupByTags(
       api as ApiPageMetadata[],
       sidebarOptions,
@@ -254,5 +282,6 @@ export default function generateSidebarSlice(
       docPath
     );
   }
+
   return sidebarSlice;
 }

package/src/types.ts

@@ -144,6 +144,13 @@ export interface SchemaPageMetadata extends ApiMetadataBase {
   markdown?: string;
 }
 
+export interface TagGroupPageMetadata extends ApiMetadataBase {
+  type: "tagGroup";
+  name: string;
+  tags: TagObject[];
+  markdown?: string;
+}
+
 export type ApiInfo = InfoObject;
 
 export interface ApiNavLink {