docusaurus-plugin-openapi-docs 4.7.1 → 5.0.0

package/src/openapi/utils/utils/openapi.ts

@@ -450,116 +450,6 @@ export function getDefinitionName(pointer?: string): string | undefined {
   return name;
 }
 
-function humanizeMultipleOfConstraint(
-  multipleOf: number | undefined
-): string | undefined {
-  if (multipleOf === undefined) {
-    return;
-  }
-  const strigifiedMultipleOf = multipleOf.toString(10);
-  if (!/^0\.0*1$/.test(strigifiedMultipleOf)) {
-    return `multiple of ${strigifiedMultipleOf}`;
-  }
-  return `decimal places <= ${strigifiedMultipleOf.split(".")[1].length}`;
-}
-
-function humanizeRangeConstraint(
-  description: string,
-  min: number | undefined,
-  max: number | undefined
-): string | undefined {
-  let stringRange;
-  if (min !== undefined && max !== undefined) {
-    if (min === max) {
-      stringRange = `= ${min} ${description}`;
-    } else {
-      stringRange = `[ ${min} .. ${max} ] ${description}`;
-    }
-  } else if (max !== undefined) {
-    stringRange = `<= ${max} ${description}`;
-  } else if (min !== undefined) {
-    if (min === 1) {
-      stringRange = "non-empty";
-    } else {
-      stringRange = `>= ${min} ${description}`;
-    }
-  }
-
-  return stringRange;
-}
-
-export function humanizeNumberRange(schema: OpenAPISchema): string | undefined {
-  const minimum =
-    typeof schema.exclusiveMinimum === "number"
-      ? Math.min(schema.exclusiveMinimum, schema.minimum ?? Infinity)
-      : schema.minimum;
-  const maximum =
-    typeof schema.exclusiveMaximum === "number"
-      ? Math.max(schema.exclusiveMaximum, schema.maximum ?? -Infinity)
-      : schema.maximum;
-  const exclusiveMinimum =
-    typeof schema.exclusiveMinimum === "number" || schema.exclusiveMinimum;
-  const exclusiveMaximum =
-    typeof schema.exclusiveMaximum === "number" || schema.exclusiveMaximum;
-
-  if (minimum !== undefined && maximum !== undefined) {
-    return `${exclusiveMinimum ? "( " : "[ "}${minimum} .. ${maximum}${
-      exclusiveMaximum ? " )" : " ]"
-    }`;
-  } else if (maximum !== undefined) {
-    return `${exclusiveMaximum ? "< " : "<= "}${maximum}`;
-  } else if (minimum !== undefined) {
-    return `${exclusiveMinimum ? "> " : ">= "}${minimum}`;
-  }
-}
-
-export function humanizeConstraints(schema: OpenAPISchema): string[] {
-  const res: string[] = [];
-
-  const stringRange = humanizeRangeConstraint(
-    "characters",
-    schema.minLength,
-    schema.maxLength
-  );
-  if (stringRange !== undefined) {
-    res.push(stringRange);
-  }
-
-  const arrayRange = humanizeRangeConstraint(
-    "items",
-    schema.minItems,
-    schema.maxItems
-  );
-  if (arrayRange !== undefined) {
-    res.push(arrayRange);
-  }
-
-  const propertiesRange = humanizeRangeConstraint(
-    "properties",
-    schema.minProperties,
-    schema.maxProperties
-  );
-  if (propertiesRange !== undefined) {
-    res.push(propertiesRange);
-  }
-
-  const multipleOfConstraint = humanizeMultipleOfConstraint(schema.multipleOf);
-  if (multipleOfConstraint !== undefined) {
-    res.push(multipleOfConstraint);
-  }
-
-  const numberRange = humanizeNumberRange(schema);
-  if (numberRange !== undefined) {
-    res.push(numberRange);
-  }
-
-  if (schema.uniqueItems) {
-    res.push("unique");
-  }
-
-  return res;
-}
-
 export function sortByRequired(fields: any[], order: string[] = []) {
   const unrequiredFields: any[] = [];
   const orderedFields: any[] = [];

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;
 
@@ -130,8 +131,8 @@ function groupByTags(
     output: string,
     doc: string | undefined
   ): string => {
-    if (doc && output.includes(doc)) {
-      return output.split(doc)[1]?.replace(/^\/+/g, "") ?? "";
+    if (doc && output.startsWith(doc + "/")) {
+      return output.substring((doc + "/").length);
     }
     const slashIndex = output.indexOf("/", 1);
     return slashIndex === -1
@@ -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
         ),
       };
 

package/lib/markdown/schema.test.js

@@ -1,181 +0,0 @@
-"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.
- * ========================================================================== */
-Object.defineProperty(exports, "__esModule", { value: true });
-const schema_1 = require("./schema");
-describe("getQualifierMessage", () => {
-    it("should render nothing", () => {
-        const actual = (0, schema_1.getQualifierMessage)({});
-        expect(actual).toBeUndefined();
-    });
-    //
-    // minLength + maxLength
-    //
-    it("should render minLength", () => {
-        const expected = "**Possible values:** `non-empty`";
-        const actual = (0, schema_1.getQualifierMessage)({ minLength: 1 });
-        expect(actual).toBe(expected);
-    });
-    it("should render maxLength", () => {
-        const expected = "**Possible values:** `<= 40 characters`";
-        const actual = (0, schema_1.getQualifierMessage)({ maxLength: 40 });
-        expect(actual).toBe(expected);
-    });
-    it("should render minLength and maxLength", () => {
-        const expected = "**Possible values:** `non-empty` and `<= 40 characters`";
-        const actual = (0, schema_1.getQualifierMessage)({ minLength: 1, maxLength: 40 });
-        expect(actual).toBe(expected);
-    });
-    //
-    // pattern
-    //
-    it("should render pattern", () => {
-        const expected = "**Possible values:** Value must match regular expression `^[a-zA-Z0-9_-]*$`";
-        const actual = (0, schema_1.getQualifierMessage)({ pattern: "^[a-zA-Z0-9_-]*$" });
-        expect(actual).toBe(expected);
-    });
-    it("should render multiple string qualifiers", () => {
-        const expected = "**Possible values:** `non-empty` and `<= 40 characters`, Value must match regular expression `^[a-zA-Z0-9_-]*$`";
-        const actual = (0, schema_1.getQualifierMessage)({
-            minLength: 1,
-            maxLength: 40,
-            pattern: "^[a-zA-Z0-9_-]*$",
-        });
-        expect(actual).toBe(expected);
-    });
-    //
-    // enum
-    //
-    it("should render enum", () => {
-        const expected = "**Possible values:** [`cat`, `dog`, `mouse`]";
-        const actual = (0, schema_1.getQualifierMessage)({ enum: ["cat", "dog", "mouse"] });
-        expect(actual).toBe(expected);
-    });
-    //
-    // minimum + maximum + exclusiveMinimum + exclusiveMaximum
-    //
-    it("should render minimum", () => {
-        const expected = "**Possible values:** `>= 1`";
-        const actual = (0, schema_1.getQualifierMessage)({ minimum: 1 });
-        expect(actual).toBe(expected);
-    });
-    it("should render maximum", () => {
-        const expected = "**Possible values:** `<= 40`";
-        const actual = (0, schema_1.getQualifierMessage)({ maximum: 40 });
-        expect(actual).toBe(expected);
-    });
-    it("should render numeric exclusiveMinimum", () => {
-        const expected = "**Possible values:** `> 1`";
-        const actual = (0, schema_1.getQualifierMessage)({ exclusiveMinimum: 1 });
-        expect(actual).toBe(expected);
-    });
-    it("should render numeric exclusiveMaximum", () => {
-        const expected = "**Possible values:** `< 40`";
-        const actual = (0, schema_1.getQualifierMessage)({ exclusiveMaximum: 40 });
-        expect(actual).toBe(expected);
-    });
-    it("should render boolean exclusiveMinimum", () => {
-        const expected = "**Possible values:** `> 1`";
-        const actual = (0, schema_1.getQualifierMessage)({ minimum: 1, exclusiveMinimum: true });
-        expect(actual).toBe(expected);
-    });
-    it("should render boolean exclusiveMaximum", () => {
-        const expected = "**Possible values:** `< 40`";
-        const actual = (0, schema_1.getQualifierMessage)({ maximum: 40, exclusiveMaximum: true });
-        expect(actual).toBe(expected);
-    });
-    it("should render minimum when exclusiveMinimum is false", () => {
-        const expected = "**Possible values:** `>= 1`";
-        const actual = (0, schema_1.getQualifierMessage)({ minimum: 1, exclusiveMinimum: false });
-        expect(actual).toBe(expected);
-    });
-    it("should render maximum when exclusiveMaximum is false", () => {
-        const expected = "**Possible values:** `<= 40`";
-        const actual = (0, schema_1.getQualifierMessage)({
-            maximum: 40,
-            exclusiveMaximum: false,
-        });
-        expect(actual).toBe(expected);
-    });
-    it("should render minimum and maximum", () => {
-        const expected = "**Possible values:** `>= 1` and `<= 40`";
-        const actual = (0, schema_1.getQualifierMessage)({ minimum: 1, maximum: 40 });
-        expect(actual).toBe(expected);
-    });
-    it("should render 0 minimum and maximum", () => {
-        const expected = "**Possible values:** `>= 0` and `<= 40`";
-        const actual = (0, schema_1.getQualifierMessage)({ minimum: 0, maximum: 40 });
-        expect(actual).toBe(expected);
-    });
-    it("should render minimum and 0 maximum", () => {
-        const expected = "**Possible values:** `>= -10` and `<= 0`";
-        const actual = (0, schema_1.getQualifierMessage)({ minimum: -10, maximum: 0 });
-        expect(actual).toBe(expected);
-    });
-    it("should render boolean exclusiveMinimum and maximum", () => {
-        const expected = "**Possible values:** `> 1` and `<= 40`";
-        const actual = (0, schema_1.getQualifierMessage)({
-            minimum: 1,
-            maximum: 40,
-            exclusiveMinimum: true,
-        });
-        expect(actual).toBe(expected);
-    });
-    it("should render minimum and boolean exclusiveMaximum", () => {
-        const expected = "**Possible values:** `>= 1` and `< 40`";
-        const actual = (0, schema_1.getQualifierMessage)({
-            minimum: 1,
-            maximum: 40,
-            exclusiveMaximum: true,
-        });
-        expect(actual).toBe(expected);
-    });
-    it("should render numeric exclusiveMinimum and maximum", () => {
-        const expected = "**Possible values:** `> 1` and `<= 40`";
-        const actual = (0, schema_1.getQualifierMessage)({
-            exclusiveMinimum: 1,
-            maximum: 40,
-        });
-        expect(actual).toBe(expected);
-    });
-    it("should render minimum and numeric exclusiveMaximum", () => {
-        const expected = "**Possible values:** `>= 1` and `< 40`";
-        const actual = (0, schema_1.getQualifierMessage)({
-            minimum: 1,
-            exclusiveMaximum: 40,
-        });
-        expect(actual).toBe(expected);
-    });
-    it("should render numeric exclusiveMinimum and boolean exclusiveMaximum", () => {
-        const expected = "**Possible values:** `> 1` and `< 40`";
-        const actual = (0, schema_1.getQualifierMessage)({
-            exclusiveMinimum: 1,
-            maximum: 40,
-            exclusiveMaximum: true,
-        });
-        expect(actual).toBe(expected);
-    });
-    it("should render nothing with empty boolean exclusiveMinimum", () => {
-        const actual = (0, schema_1.getQualifierMessage)({
-            exclusiveMinimum: true,
-        });
-        expect(actual).toBeUndefined();
-    });
-    it("should render nothing with empty boolean exclusiveMaximum", () => {
-        const actual = (0, schema_1.getQualifierMessage)({
-            exclusiveMaximum: true,
-        });
-        expect(actual).toBeUndefined();
-    });
-    it("should render nothing with empty boolean exclusiveMinimum and exclusiveMaximum", () => {
-        const actual = (0, schema_1.getQualifierMessage)({
-            exclusiveMinimum: true,
-            exclusiveMaximum: true,
-        });
-        expect(actual).toBeUndefined();
-    });
-});

package/src/markdown/schema.test.ts

@@ -1,208 +0,0 @@
-/* ============================================================================
- * 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 { getQualifierMessage } from "./schema";
-
-describe("getQualifierMessage", () => {
-  it("should render nothing", () => {
-    const actual = getQualifierMessage({});
-    expect(actual).toBeUndefined();
-  });
-
-  //
-  // minLength + maxLength
-  //
-  it("should render minLength", () => {
-    const expected = "**Possible values:** `non-empty`";
-    const actual = getQualifierMessage({ minLength: 1 });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render maxLength", () => {
-    const expected = "**Possible values:** `<= 40 characters`";
-    const actual = getQualifierMessage({ maxLength: 40 });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render minLength and maxLength", () => {
-    const expected = "**Possible values:** `non-empty` and `<= 40 characters`";
-    const actual = getQualifierMessage({ minLength: 1, maxLength: 40 });
-    expect(actual).toBe(expected);
-  });
-
-  //
-  // pattern
-  //
-  it("should render pattern", () => {
-    const expected =
-      "**Possible values:** Value must match regular expression `^[a-zA-Z0-9_-]*$`";
-    const actual = getQualifierMessage({ pattern: "^[a-zA-Z0-9_-]*$" });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render multiple string qualifiers", () => {
-    const expected =
-      "**Possible values:** `non-empty` and `<= 40 characters`, Value must match regular expression `^[a-zA-Z0-9_-]*$`";
-    const actual = getQualifierMessage({
-      minLength: 1,
-      maxLength: 40,
-      pattern: "^[a-zA-Z0-9_-]*$",
-    });
-    expect(actual).toBe(expected);
-  });
-
-  //
-  // enum
-  //
-  it("should render enum", () => {
-    const expected = "**Possible values:** [`cat`, `dog`, `mouse`]";
-    const actual = getQualifierMessage({ enum: ["cat", "dog", "mouse"] });
-    expect(actual).toBe(expected);
-  });
-
-  //
-  // minimum + maximum + exclusiveMinimum + exclusiveMaximum
-  //
-  it("should render minimum", () => {
-    const expected = "**Possible values:** `>= 1`";
-    const actual = getQualifierMessage({ minimum: 1 });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render maximum", () => {
-    const expected = "**Possible values:** `<= 40`";
-    const actual = getQualifierMessage({ maximum: 40 });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render numeric exclusiveMinimum", () => {
-    const expected = "**Possible values:** `> 1`";
-    const actual = getQualifierMessage({ exclusiveMinimum: 1 });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render numeric exclusiveMaximum", () => {
-    const expected = "**Possible values:** `< 40`";
-    const actual = getQualifierMessage({ exclusiveMaximum: 40 });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render boolean exclusiveMinimum", () => {
-    const expected = "**Possible values:** `> 1`";
-    const actual = getQualifierMessage({ minimum: 1, exclusiveMinimum: true });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render boolean exclusiveMaximum", () => {
-    const expected = "**Possible values:** `< 40`";
-    const actual = getQualifierMessage({ maximum: 40, exclusiveMaximum: true });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render minimum when exclusiveMinimum is false", () => {
-    const expected = "**Possible values:** `>= 1`";
-    const actual = getQualifierMessage({ minimum: 1, exclusiveMinimum: false });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render maximum when exclusiveMaximum is false", () => {
-    const expected = "**Possible values:** `<= 40`";
-    const actual = getQualifierMessage({
-      maximum: 40,
-      exclusiveMaximum: false,
-    });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render minimum and maximum", () => {
-    const expected = "**Possible values:** `>= 1` and `<= 40`";
-    const actual = getQualifierMessage({ minimum: 1, maximum: 40 });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render 0 minimum and maximum", () => {
-    const expected = "**Possible values:** `>= 0` and `<= 40`";
-    const actual = getQualifierMessage({ minimum: 0, maximum: 40 });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render minimum and 0 maximum", () => {
-    const expected = "**Possible values:** `>= -10` and `<= 0`";
-    const actual = getQualifierMessage({ minimum: -10, maximum: 0 });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render boolean exclusiveMinimum and maximum", () => {
-    const expected = "**Possible values:** `> 1` and `<= 40`";
-    const actual = getQualifierMessage({
-      minimum: 1,
-      maximum: 40,
-      exclusiveMinimum: true,
-    });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render minimum and boolean exclusiveMaximum", () => {
-    const expected = "**Possible values:** `>= 1` and `< 40`";
-    const actual = getQualifierMessage({
-      minimum: 1,
-      maximum: 40,
-      exclusiveMaximum: true,
-    });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render numeric exclusiveMinimum and maximum", () => {
-    const expected = "**Possible values:** `> 1` and `<= 40`";
-    const actual = getQualifierMessage({
-      exclusiveMinimum: 1,
-      maximum: 40,
-    });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render minimum and numeric exclusiveMaximum", () => {
-    const expected = "**Possible values:** `>= 1` and `< 40`";
-    const actual = getQualifierMessage({
-      minimum: 1,
-      exclusiveMaximum: 40,
-    });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render numeric exclusiveMinimum and boolean exclusiveMaximum", () => {
-    const expected = "**Possible values:** `> 1` and `< 40`";
-    const actual = getQualifierMessage({
-      exclusiveMinimum: 1,
-      maximum: 40,
-      exclusiveMaximum: true,
-    });
-    expect(actual).toBe(expected);
-  });
-
-  it("should render nothing with empty boolean exclusiveMinimum", () => {
-    const actual = getQualifierMessage({
-      exclusiveMinimum: true,
-    });
-    expect(actual).toBeUndefined();
-  });
-
-  it("should render nothing with empty boolean exclusiveMaximum", () => {
-    const actual = getQualifierMessage({
-      exclusiveMaximum: true,
-    });
-    expect(actual).toBeUndefined();
-  });
-
-  it("should render nothing with empty boolean exclusiveMinimum and exclusiveMaximum", () => {
-    const actual = getQualifierMessage({
-      exclusiveMinimum: true,
-      exclusiveMaximum: true,
-    });
-    expect(actual).toBeUndefined();
-  });
-});