docusaurus-plugin-openapi-docs 0.0.0-1110 → 0.0.0-1151

package/lib/openapi/utils/loadAndResolveSpec.js

@@ -104,7 +104,7 @@ async function resolveJsonRefs(specUrlOrObject) {
     }
 }
 async function loadAndResolveSpec(specUrlOrObject) {
-    const config = new openapi_core_1.Config({});
+    const config = await (0, openapi_core_1.createConfig)({});
     const bundleOpts = {
         config,
         base: process.cwd(),
@@ -121,9 +121,10 @@ async function loadAndResolveSpec(specUrlOrObject) {
     // Force dereference ?
     // bundleOpts["dereference"] = true;
     const { bundle: { parsed }, } = await (0, openapi_core_1.bundle)(bundleOpts);
+    const parsedSpec = parsed;
     //Pre-processing before resolving JSON refs
-    if (parsed.components) {
-        for (let [component, type] of Object.entries(parsed.components)) {
+    if (parsedSpec.components) {
+        for (let [component, type] of Object.entries(parsedSpec.components)) {
             if (component === "schemas") {
                 for (let [schemaKey, schemaValue] of Object.entries(type)) {
                     const title = schemaValue["title"];
@@ -134,7 +135,7 @@ async function loadAndResolveSpec(specUrlOrObject) {
             }
         }
     }
-    const resolved = await resolveJsonRefs(parsed);
+    const resolved = await resolveJsonRefs(parsedSpec);
     // Force serialization and replace circular $ref pointers
     // @ts-ignore
     const serialized = JSON.stringify(resolved, serializer());

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-1110",
+  "version": "0.0.0-1151",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -40,10 +40,10 @@
     "eslint-plugin-prettier": "^5.5.1"
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^11.5.4",
-    "@redocly/openapi-core": "^1.34.3",
+    "@apidevtools/json-schema-ref-parser": "^15.3.3",
+    "@redocly/openapi-core": "^2.25.2",
     "allof-merge": "^0.6.6",
-    "chalk": "^4.1.2",
+    "chalk": "^5.6.2",
     "clsx": "^2.1.1",
     "fs-extra": "^11.3.0",
     "json-pointer": "^0.6.2",
@@ -65,5 +65,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "e4a99880178b660e4ba688b2d13aef1280752322"
+  "gitHead": "ce9f21391974edb2ad7a1a7c2e39700a27bc5123"
 }

package/src/openapi/utils/loadAndResolveSpec.ts

@@ -6,9 +6,8 @@
  * ========================================================================== */
 
 import $RefParser from "@apidevtools/json-schema-ref-parser";
-import { bundle, Config } from "@redocly/openapi-core";
+import { bundle, createConfig } from "@redocly/openapi-core";
 import type { Source, Document } from "@redocly/openapi-core";
-import { ResolvedConfig } from "@redocly/openapi-core/lib/config";
 import chalk from "chalk";
 // @ts-ignore
 import { convertObj } from "swagger2openapi";
@@ -116,7 +115,7 @@ async function resolveJsonRefs(specUrlOrObject: object | string) {
 }
 
 export async function loadAndResolveSpec(specUrlOrObject: object | string) {
-  const config = new Config({} as ResolvedConfig);
+  const config = await createConfig({});
   const bundleOpts = {
     config,
     base: process.cwd(),
@@ -137,10 +136,13 @@ export async function loadAndResolveSpec(specUrlOrObject: object | string) {
   const {
     bundle: { parsed },
   } = await bundle(bundleOpts);
+  const parsedSpec = parsed as any;
 
   //Pre-processing before resolving JSON refs
-  if (parsed.components) {
-    for (let [component, type] of Object.entries(parsed.components) as any) {
+  if (parsedSpec.components) {
+    for (let [component, type] of Object.entries(
+      parsedSpec.components
+    ) as any) {
       if (component === "schemas") {
         for (let [schemaKey, schemaValue] of Object.entries(type) as any) {
           const title: string | undefined = schemaValue["title"];
@@ -152,7 +154,7 @@ export async function loadAndResolveSpec(specUrlOrObject: object | string) {
     }
   }
 
-  const resolved = await resolveJsonRefs(parsed);
+  const resolved = await resolveJsonRefs(parsedSpec);
 
   // Force serialization and replace circular $ref pointers
   // @ts-ignore

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
         ),
       };