docusaurus-plugin-openapi-docs 0.0.0-1109 → 0.0.0-1130

package/lib/sidebars/index.js

@@ -45,7 +45,7 @@ const createDocItem = (item, { sidebarOptions: { customProps }, basePath }) => {
         className: className ? className : undefined,
     };
 };
-function groupByTags(items, sidebarOptions, options, tags, docPath) {
+function groupByTags(items, sidebarOptions, options, tags, docPath, tagGroupKey) {
     var _a, _b;
     let { outputDir, label, showSchemas } = options;
     // Remove trailing slash before proceeding
@@ -102,9 +102,11 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
     if (infoItems.length === 1) {
         const infoItem = infoItems[0];
         const id = infoItem.id;
+        const docId = basePath === "" || undefined ? `${id}` : `${basePath}/${id}`;
         rootIntroDoc = {
             type: "doc",
-            id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
+            id: docId,
+            ...(tagGroupKey && { key: (0, lodash_1.kebabCase)(`${tagGroupKey}-${docId}`) }),
         };
     }
     const tagged = apiTags
@@ -146,13 +148,27 @@ function groupByTags(items, sidebarOptions, options, tags, docPath) {
         }
         const taggedApiItems = apiItems.filter((item) => { var _a; return !!((_a = item.api.tags) === null || _a === void 0 ? void 0 : _a.includes(tag)); });
         const taggedSchemaItems = schemaItems.filter((item) => { var _a; return !!((_a = item.schema["x-tags"]) === null || _a === void 0 ? void 0 : _a.includes(tag)); });
+        const categoryLabel = (_a = tagObject === null || tagObject === void 0 ? void 0 : tagObject["x-displayName"]) !== null && _a !== void 0 ? _a : tag;
+        const categoryKey = tagGroupKey
+            ? (0, lodash_1.kebabCase)(`${tagGroupKey}-${categoryLabel}`)
+            : undefined;
         return {
             type: "category",
-            label: (_a = tagObject === null || tagObject === void 0 ? void 0 : tagObject["x-displayName"]) !== null && _a !== void 0 ? _a : tag,
+            label: categoryLabel,
+            ...(categoryKey && { key: categoryKey }),
             link: linkConfig,
             collapsible: sidebarCollapsible,
             collapsed: sidebarCollapsed,
-            items: [...taggedSchemaItems, ...taggedApiItems].map((item) => createDocItemFn(item, createDocItemFnContext)),
+            items: [...taggedSchemaItems, ...taggedApiItems].map((item) => {
+                const docItem = createDocItemFn(item, createDocItemFnContext);
+                if (tagGroupKey && docItem.type === "doc") {
+                    return {
+                        ...docItem,
+                        key: (0, lodash_1.kebabCase)(`${tagGroupKey}-${tag}-${docItem.id}`),
+                    };
+                }
+                return docItem;
+            }),
         };
     })
         .filter((item) => item.items.length > 0); // Filter out any categories with no items.
@@ -208,12 +224,13 @@ function generateSidebarSlice(sidebarOptions, options, api, tags, docPath, tagGr
                     filteredTags.push(tag);
                 }
             });
+            const tagGroupKey = (0, lodash_1.kebabCase)(tagGroup.name);
             const groupCategory = {
                 type: "category",
                 label: tagGroup.name,
                 collapsible: true,
                 collapsed: true,
-                items: groupByTags(api, sidebarOptions, options, [filteredTags], docPath),
+                items: groupByTags(api, sidebarOptions, options, [filteredTags], docPath, tagGroupKey),
             };
             if (options.showSchemas) {
                 // For the first tagGroup, save the generated "Schemas" category for later.

package/lib/sidebars/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/sidebars/index.test.js

@@ -0,0 +1,68 @@
+"use strict";
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = __importDefault(require("./index"));
+describe("generateSidebarSlice", () => {
+    describe("tagGroup with overlapping tags", () => {
+        const mockApiItems = [
+            {
+                type: "api",
+                id: "get-books",
+                unversionedId: "get-books",
+                title: "Get Books",
+                description: "",
+                source: "",
+                sourceDirName: "",
+                permalink: "/get-books",
+                frontMatter: {},
+                api: {
+                    method: "get",
+                    path: "/books",
+                    tags: ["Books", "Deprecated"],
+                    jsonRequestBodyExample: "",
+                    info: { title: "Test API", version: "1.0.0" },
+                },
+            },
+        ];
+        const mockTags = [
+            [
+                { name: "Books", description: "Book operations" },
+                { name: "Deprecated", description: "Deprecated endpoints" },
+            ],
+        ];
+        const mockTagGroups = [
+            { name: "Library", tags: ["Books"] },
+            { name: "Deprecation", tags: ["Deprecated"] },
+        ];
+        function collectKeys(obj) {
+            const keys = [];
+            JSON.stringify(obj, (k, v) => {
+                if (k === "key" && typeof v === "string") {
+                    keys.push(v);
+                }
+                return v;
+            });
+            return keys;
+        }
+        it("should generate unique keys for items appearing in multiple tagGroups", () => {
+            const result = (0, index_1.default)({ groupPathsBy: "tagGroup" }, { outputDir: "docs/test", specPath: "" }, mockApiItems, mockTags, "", mockTagGroups);
+            const keys = collectKeys(result);
+            expect(keys.length).toBeGreaterThan(0);
+            expect(new Set(keys).size).toBe(keys.length);
+        });
+        it("should include tagGroup name in keys to differentiate same items", () => {
+            const result = (0, index_1.default)({ groupPathsBy: "tagGroup" }, { outputDir: "docs/test", specPath: "" }, mockApiItems, mockTags, "", mockTagGroups);
+            const keys = collectKeys(result);
+            expect(keys.filter((k) => k.includes("library")).length).toBeGreaterThan(0);
+            expect(keys.filter((k) => k.includes("deprecation")).length).toBeGreaterThan(0);
+        });
+    });
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-plugin-openapi-docs",
   "description": "OpenAPI plugin for Docusaurus.",
-  "version": "0.0.0-1109",
+  "version": "0.0.0-1130",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -65,5 +65,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "96c769dd3f97f033600a157fb9b607b5a05b439e"
+  "gitHead": "5e9591e0e848677c7589a091580feffcc0a86b41"
 }

package/src/sidebars/index.test.ts

@@ -0,0 +1,94 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+import type { TagGroupObject, TagObject } from "../openapi/types";
+import type { ApiMetadata } from "../types";
+import generateSidebarSlice from "./index";
+
+describe("generateSidebarSlice", () => {
+  describe("tagGroup with overlapping tags", () => {
+    const mockApiItems: ApiMetadata[] = [
+      {
+        type: "api",
+        id: "get-books",
+        unversionedId: "get-books",
+        title: "Get Books",
+        description: "",
+        source: "",
+        sourceDirName: "",
+        permalink: "/get-books",
+        frontMatter: {},
+        api: {
+          method: "get",
+          path: "/books",
+          tags: ["Books", "Deprecated"],
+          jsonRequestBodyExample: "",
+          info: { title: "Test API", version: "1.0.0" },
+        },
+      } as ApiMetadata,
+    ];
+
+    const mockTags: TagObject[][] = [
+      [
+        { name: "Books", description: "Book operations" },
+        { name: "Deprecated", description: "Deprecated endpoints" },
+      ],
+    ];
+
+    const mockTagGroups: TagGroupObject[] = [
+      { name: "Library", tags: ["Books"] },
+      { name: "Deprecation", tags: ["Deprecated"] },
+    ];
+
+    function collectKeys(obj: unknown): string[] {
+      const keys: string[] = [];
+      JSON.stringify(obj, (k, v) => {
+        if (k === "key" && typeof v === "string") {
+          keys.push(v);
+        }
+        return v;
+      });
+      return keys;
+    }
+
+    it("should generate unique keys for items appearing in multiple tagGroups", () => {
+      const result = generateSidebarSlice(
+        { groupPathsBy: "tagGroup" },
+        { outputDir: "docs/test", specPath: "" },
+        mockApiItems,
+        mockTags,
+        "",
+        mockTagGroups
+      );
+
+      const keys = collectKeys(result);
+
+      expect(keys.length).toBeGreaterThan(0);
+      expect(new Set(keys).size).toBe(keys.length);
+    });
+
+    it("should include tagGroup name in keys to differentiate same items", () => {
+      const result = generateSidebarSlice(
+        { groupPathsBy: "tagGroup" },
+        { outputDir: "docs/test", specPath: "" },
+        mockApiItems,
+        mockTags,
+        "",
+        mockTagGroups
+      );
+
+      const keys = collectKeys(result);
+
+      expect(keys.filter((k) => k.includes("library")).length).toBeGreaterThan(
+        0
+      );
+      expect(
+        keys.filter((k) => k.includes("deprecation")).length
+      ).toBeGreaterThan(0);
+    });
+  });
+});

package/src/sidebars/index.ts

@@ -77,7 +77,8 @@ function groupByTags(
   sidebarOptions: SidebarOptions,
   options: APIOptions,
   tags: TagObject[][],
-  docPath: string
+  docPath: string,
+  tagGroupKey?: string
 ): ProcessedSidebar {
   let { outputDir, label, showSchemas } = options;
 
@@ -152,9 +153,11 @@ function groupByTags(
   if (infoItems.length === 1) {
     const infoItem = infoItems[0];
     const id = infoItem.id;
+    const docId = basePath === "" || undefined ? `${id}` : `${basePath}/${id}`;
     rootIntroDoc = {
       type: "doc" as const,
-      id: basePath === "" || undefined ? `${id}` : `${basePath}/${id}`,
+      id: docId,
+      ...(tagGroupKey && { key: kebabCase(`${tagGroupKey}-${docId}`) }),
     };
   }
 
@@ -219,15 +222,28 @@ function groupByTags(
         (item) => !!item.schema["x-tags"]?.includes(tag)
       );
 
+      const categoryLabel = tagObject?.["x-displayName"] ?? tag;
+      const categoryKey = tagGroupKey
+        ? kebabCase(`${tagGroupKey}-${categoryLabel}`)
+        : undefined;
+
       return {
         type: "category" as const,
-        label: tagObject?.["x-displayName"] ?? tag,
+        label: categoryLabel,
+        ...(categoryKey && { key: categoryKey }),
         link: linkConfig,
         collapsible: sidebarCollapsible,
         collapsed: sidebarCollapsed,
-        items: [...taggedSchemaItems, ...taggedApiItems].map((item) =>
-          createDocItemFn(item, createDocItemFnContext)
-        ),
+        items: [...taggedSchemaItems, ...taggedApiItems].map((item) => {
+          const docItem = createDocItemFn(item, createDocItemFnContext);
+          if (tagGroupKey && docItem.type === "doc") {
+            return {
+              ...docItem,
+              key: kebabCase(`${tagGroupKey}-${tag}-${docItem.id}`),
+            };
+          }
+          return docItem;
+        }),
       };
     })
     .filter((item) => item.items.length > 0); // Filter out any categories with no items.
@@ -296,6 +312,8 @@ export default function generateSidebarSlice(
         }
       });
 
+      const tagGroupKey = kebabCase(tagGroup.name);
+
       const groupCategory = {
         type: "category" as const,
         label: tagGroup.name,
@@ -306,7 +324,8 @@ export default function generateSidebarSlice(
           sidebarOptions,
           options,
           [filteredTags],
-          docPath
+          docPath,
+          tagGroupKey
         ),
       };