docusaurus-theme-openapi-docs 0.0.0-1314 → 0.0.0-1332

package/lib/theme/Schema/normalize.test.js

@@ -0,0 +1,271 @@
+"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 normalize_1 = require("./normalize");
+describe("normalizeSchema", () => {
+  it("returns the input as-is (identity-stable pass-through)", () => {
+    const schema = { type: "object", properties: { a: { type: "string" } } };
+    expect((0, normalize_1.normalizeSchema)(schema)).toBe(schema);
+  });
+  it("handles null, undefined, and primitives", () => {
+    expect((0, normalize_1.normalizeSchema)(null)).toBeNull();
+    expect((0, normalize_1.normalizeSchema)(undefined)).toBeUndefined();
+    expect((0, normalize_1.normalizeSchema)("string")).toBe("string");
+    expect((0, normalize_1.normalizeSchema)(42)).toBe(42);
+  });
+});
+describe("mergeAllOf", () => {
+  it("merges allOf members into a flat schema", () => {
+    const schema = {
+      allOf: [
+        { type: "object", properties: { a: { type: "string" } } },
+        { type: "object", properties: { b: { type: "number" } } },
+      ],
+    };
+    const result = (0, normalize_1.mergeAllOf)(schema);
+    expect(result.allOf).toBeUndefined();
+    expect(result.properties.a).toEqual({ type: "string" });
+    expect(result.properties.b).toEqual({ type: "number" });
+  });
+  it("strips conflicting additionalProperties: false from allOf members", () => {
+    const schema = {
+      allOf: [
+        {
+          type: "object",
+          properties: { a: { type: "string" } },
+          additionalProperties: false,
+        },
+        {
+          type: "object",
+          properties: { b: { type: "number" } },
+          additionalProperties: false,
+        },
+      ],
+    };
+    const result = (0, normalize_1.mergeAllOf)(schema);
+    expect(result.properties.a).toBeDefined();
+    expect(result.properties.b).toBeDefined();
+  });
+  it("preserves both properties and oneOf when merging incompatible-shape members", () => {
+    const result = (0, normalize_1.mergeAllOf)({
+      allOf: [
+        { type: "object", properties: { id: { type: "string" } } },
+        { oneOf: [{ title: "a" }, { title: "b" }] },
+      ],
+    });
+    expect(result.properties.id).toBeDefined();
+    expect(result.oneOf).toHaveLength(2);
+  });
+});
+describe("foldSiblingsIntoBranches", () => {
+  it("returns schema unchanged when no oneOf/anyOf is present", () => {
+    const schema = { type: "object", properties: { a: { type: "string" } } };
+    expect((0, normalize_1.foldSiblingsIntoBranches)(schema)).toBe(schema);
+  });
+  it("returns schema unchanged when branches have no siblings", () => {
+    const schema = {
+      oneOf: [{ properties: { a: { type: "string" } } }],
+    };
+    expect((0, normalize_1.foldSiblingsIntoBranches)(schema)).toBe(schema);
+  });
+  it("returns schema unchanged when a discriminator is present", () => {
+    const schema = {
+      discriminator: { propertyName: "type" },
+      properties: { shared: { type: "string" } },
+      oneOf: [{ properties: { a: { type: "number" } } }],
+    };
+    expect((0, normalize_1.foldSiblingsIntoBranches)(schema)).toBe(schema);
+  });
+  it("folds sibling properties into oneOf branches", () => {
+    const schema = {
+      properties: { shared: { type: "string" } },
+      oneOf: [
+        { properties: { a: { type: "number" } } },
+        { properties: { b: { type: "boolean" } } },
+      ],
+    };
+    const result = (0, normalize_1.foldSiblingsIntoBranches)(schema);
+    expect(result.properties).toBeUndefined();
+    expect(result.oneOf).toHaveLength(2);
+    expect(result.oneOf[0].properties.shared).toBeDefined();
+    expect(result.oneOf[0].properties.a).toBeDefined();
+  });
+  it("folds sibling properties into anyOf branches", () => {
+    const schema = {
+      properties: { shared: { type: "string" } },
+      anyOf: [
+        { properties: { a: { type: "number" } } },
+        { properties: { b: { type: "boolean" } } },
+      ],
+    };
+    const result = (0, normalize_1.foldSiblingsIntoBranches)(schema);
+    expect(result.properties).toBeUndefined();
+    expect(result.anyOf).toHaveLength(2);
+    expect(result.anyOf[1].properties.shared).toBeDefined();
+    expect(result.anyOf[1].properties.b).toBeDefined();
+  });
+  it("preserves metadata and x-extension keys when folding", () => {
+    const schema = {
+      title: "Test",
+      description: "desc",
+      deprecated: true,
+      "x-vendor": true,
+      properties: { shared: { type: "string" } },
+      anyOf: [{ properties: { a: { type: "number" } } }],
+    };
+    const result = (0, normalize_1.foldSiblingsIntoBranches)(schema);
+    expect(result.title).toBe("Test");
+    expect(result.description).toBe("desc");
+    expect(result.deprecated).toBe(true);
+    expect(result["x-vendor"]).toBe(true);
+    expect(result.properties).toBeUndefined();
+  });
+  it("strips non-metadata keys from result", () => {
+    const schema = {
+      type: "object",
+      required: ["shared"],
+      properties: { shared: { type: "string" } },
+      items: { type: "string" },
+      oneOf: [{ properties: { a: { type: "number" } } }],
+    };
+    const result = (0, normalize_1.foldSiblingsIntoBranches)(schema);
+    expect(result.type).toBeUndefined();
+    expect(result.required).toBeUndefined();
+    expect(result.properties).toBeUndefined();
+    expect(result.items).toBeUndefined();
+    expect(result.oneOf).toHaveLength(1);
+  });
+});
+describe("getDiscriminator", () => {
+  it("returns direct discriminator", () => {
+    const schema = { discriminator: { propertyName: "type" } };
+    expect((0, normalize_1.getDiscriminator)(schema)).toEqual({
+      propertyName: "type",
+    });
+  });
+  it("finds discriminator in oneOf branches", () => {
+    const schema = {
+      oneOf: [{ discriminator: { propertyName: "kind" } }, { type: "string" }],
+    };
+    expect((0, normalize_1.getDiscriminator)(schema)).toEqual({
+      propertyName: "kind",
+    });
+  });
+  it("finds discriminator in anyOf branches", () => {
+    const schema = {
+      anyOf: [
+        { type: "string" },
+        { discriminator: { propertyName: "variant" } },
+      ],
+    };
+    expect((0, normalize_1.getDiscriminator)(schema)).toEqual({
+      propertyName: "variant",
+    });
+  });
+  it("finds discriminator in allOf branches", () => {
+    const schema = {
+      allOf: [
+        { properties: { id: { type: "string" } } },
+        { discriminator: { propertyName: "type" } },
+      ],
+    };
+    expect((0, normalize_1.getDiscriminator)(schema)).toEqual({
+      propertyName: "type",
+    });
+  });
+  it("returns undefined when no discriminator exists", () => {
+    const schema = {
+      type: "object",
+      properties: { name: { type: "string" } },
+    };
+    expect((0, normalize_1.getDiscriminator)(schema)).toBeUndefined();
+  });
+  it("returns undefined for null/primitive input", () => {
+    expect((0, normalize_1.getDiscriminator)(null)).toBeUndefined();
+    expect((0, normalize_1.getDiscriminator)("string")).toBeUndefined();
+  });
+  it("caches results for same object reference", () => {
+    const inner = { discriminator: { propertyName: "type" } };
+    const schema = { oneOf: [inner] };
+    const first = (0, normalize_1.getDiscriminator)(schema);
+    const second = (0, normalize_1.getDiscriminator)(schema);
+    expect(first).toBe(second);
+  });
+  it("handles cycles without infinite recursion", () => {
+    const a = { properties: {} };
+    const b = { properties: { a } };
+    a.properties.b = b;
+    expect(() => (0, normalize_1.getDiscriminator)(a)).not.toThrow();
+    expect((0, normalize_1.getDiscriminator)(a)).toBeUndefined();
+  });
+});
+describe("findPropertyDeep", () => {
+  it("returns property at top level", () => {
+    const schema = { properties: { foo: { type: "string" } } };
+    expect((0, normalize_1.findPropertyDeep)(schema, "foo")).toEqual({
+      type: "string",
+    });
+  });
+  it("finds property in oneOf branches", () => {
+    const schema = {
+      oneOf: [
+        { properties: { a: { type: "string" } } },
+        { properties: { b: { type: "number" } } },
+      ],
+    };
+    expect((0, normalize_1.findPropertyDeep)(schema, "a")).toEqual({
+      type: "string",
+    });
+    expect((0, normalize_1.findPropertyDeep)(schema, "b")).toEqual({
+      type: "number",
+    });
+  });
+  it("finds property in anyOf branches", () => {
+    const schema = {
+      anyOf: [{ properties: { x: { type: "integer" } } }],
+    };
+    expect((0, normalize_1.findPropertyDeep)(schema, "x")).toEqual({
+      type: "integer",
+    });
+  });
+  it("finds property in allOf branches", () => {
+    const schema = {
+      allOf: [{ properties: { y: { type: "boolean" } } }],
+    };
+    expect((0, normalize_1.findPropertyDeep)(schema, "y")).toEqual({
+      type: "boolean",
+    });
+  });
+  it("returns undefined when property not found", () => {
+    const schema = { properties: { foo: { type: "string" } } };
+    expect((0, normalize_1.findPropertyDeep)(schema, "bar")).toBeUndefined();
+  });
+  it("returns undefined for null/primitive input", () => {
+    expect((0, normalize_1.findPropertyDeep)(null, "foo")).toBeUndefined();
+    expect((0, normalize_1.findPropertyDeep)("string", "foo")).toBeUndefined();
+  });
+  it("handles cycles without infinite recursion", () => {
+    const a = { properties: {} };
+    a.oneOf = [a];
+    expect(() => (0, normalize_1.findPropertyDeep)(a, "foo")).not.toThrow();
+    expect((0, normalize_1.findPropertyDeep)(a, "foo")).toBeUndefined();
+  });
+});
+describe("isCircularMarker", () => {
+  it("returns true for circular marker strings", () => {
+    expect((0, normalize_1.isCircularMarker)("circular(Title)")).toBe(true);
+    expect((0, normalize_1.isCircularMarker)("circular()")).toBe(true);
+  });
+  it("returns false for other values", () => {
+    expect((0, normalize_1.isCircularMarker)("normal string")).toBe(false);
+    expect((0, normalize_1.isCircularMarker)(null)).toBe(false);
+    expect((0, normalize_1.isCircularMarker)(undefined)).toBe(false);
+    expect((0, normalize_1.isCircularMarker)({})).toBe(false);
+    expect((0, normalize_1.isCircularMarker)(42)).toBe(false);
+  });
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-theme-openapi-docs",
   "description": "OpenAPI theme for Docusaurus.",
-  "version": "0.0.0-1314",
+  "version": "0.0.0-1332",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -38,7 +38,7 @@
     "@types/postman-collection": "^3.5.11",
     "@types/react-modal": "^3.16.3",
     "concurrently": "^10.0.3",
-    "docusaurus-plugin-openapi-docs": "0.0.0-1314",
+    "docusaurus-plugin-openapi-docs": "0.0.0-1332",
     "docusaurus-plugin-sass": "^0.2.6",
     "eslint-plugin-prettier": "^5.5.1"
   },
@@ -82,5 +82,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "c8bf336e01d040d09ab74df031b680dce9e482fc"
+  "gitHead": "42a942eaf3b45f41329f21e1bf0ac9dde70cbd1a"
 }

package/src/theme/Schema/index.tsx

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import React, { useCallback } from "react";
+import React, { useCallback, useMemo } from "react";
 
 import { translate } from "@docusaurus/Translate";
 import { setSchemaSelection } from "@theme/ApiExplorer/SchemaSelection/slice";
@@ -14,6 +14,14 @@ import { ClosingArrayBracket, OpeningArrayBracket } from "@theme/ArrayBrackets";
 import Details from "@theme/Details";
 import DiscriminatorTabs from "@theme/DiscriminatorTabs";
 import Markdown from "@theme/Markdown";
+import {
+  findPropertyDeep,
+  foldSiblingsIntoBranches,
+  getDiscriminator,
+  isCircularMarker,
+  mergeAllOf,
+  normalizeSchema,
+} from "@theme/Schema/normalize";
 import {
   SchemaDepthProvider,
   useSchemaDepth,
@@ -22,192 +30,12 @@ import {
 import SchemaItem from "@theme/SchemaItem";
 import SchemaTabs from "@theme/SchemaTabs";
 import TabItem from "@theme/TabItem";
-// eslint-disable-next-line import/no-extraneous-dependencies
-import { merge } from "allof-merge";
 import clsx from "clsx";
 import isEmpty from "lodash/isEmpty";
 
 import { getQualifierMessage, getSchemaName } from "../../markdown/schema";
 import type { SchemaObject } from "../../types.d";
 
-// eslint-disable-next-line import/no-extraneous-dependencies
-// const jsonSchemaMergeAllOf = require("json-schema-merge-allof");
-
-/**
- * Strip `additionalProperties: false` from sibling allOf members so the
- * strict-AND semantics of `allof-merge` don't collapse the result to an
- * unsatisfiable empty schema.
- *
- * Per JSON Schema, two allOf members that each set `additionalProperties: false`
- * with disjoint `properties` sets define an unsatisfiable schema (no value can
- * satisfy both — each member rejects the other's properties). `allof-merge` is
- * technically correct to drop all properties in that case, but it leaves the
- * rendered schema blank.
- *
- * NSwag and Swashbuckle emit this pattern by default whenever a model uses
- * inheritance/composition, so it's the dominant style for .NET-generated specs.
- * Redoc, Swagger UI, and Stoplight all union the properties and ignore the
- * conflicting flag — the approach this helper emulates by stripping the flag
- * before delegating to `allof-merge`. The flag is render-irrelevant anyway:
- * `additionalProperties: false` is treated identically to `undefined` by the
- * AdditionalProperties component below (line ~641).
- *
- * Strips from every allOf member whenever the parent has ≥2 members. The
- * collapse triggers symmetrically (both siblings strict) or asymmetrically
- * (one strict member rejects another's properties as "additional"), so the
- * presence of multiple members is the right gate. Single-member allOf is left
- * alone — it can't conflict with anything.
- *
- * See https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/1119
- * Mirrored in plugin: docusaurus-plugin-openapi-docs/src/markdown/createSchema.ts
- */
-const stripConflictingAdditionalProps = (node: any): any => {
-  if (Array.isArray(node)) return node.map(stripConflictingAdditionalProps);
-  if (!node || typeof node !== "object") return node;
-
-  let working: any = node;
-  if (Array.isArray(node.allOf) && node.allOf.length > 1) {
-    const hasStrictMember = node.allOf.some(
-      (m: any) => m && m.additionalProperties === false
-    );
-    if (hasStrictMember) {
-      working = {
-        ...node,
-        allOf: node.allOf.map((m: any) => {
-          if (m && m.additionalProperties === false) {
-            const { additionalProperties: _drop, ...rest } = m;
-            return rest;
-          }
-          return m;
-        }),
-      };
-    }
-  }
-
-  const result: any = {};
-  for (const [k, v] of Object.entries(working)) {
-    result[k] = stripConflictingAdditionalProps(v);
-  }
-  return result;
-};
-
-const mergeAllOf = (allOf: any) => {
-  const onMergeError = (msg: string) => {
-    console.warn(msg);
-  };
-
-  const mergedSchemas = merge(stripConflictingAdditionalProps(allOf), {
-    onMergeError,
-  });
-
-  return mergedSchemas ?? {};
-};
-
-/**
- * Fold sibling fields into each `oneOf`/`anyOf` branch via allOf-merge, so each
- * branch is self-contained. Mirrors Redoc's `SchemaModel.initOneOf` behavior.
- * Without this, when an `allOf` override redefines a nested property with
- * `oneOf`, the merged schema ends up with both `properties` and `oneOf` as
- * siblings — and the renderer prints the shared properties twice.
- *
- * See https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/1218
- */
-const foldSiblingsIntoBranches = (schema: any): any => {
-  const branchKey = schema?.oneOf
-    ? "oneOf"
-    : schema?.anyOf
-      ? "anyOf"
-      : undefined;
-  if (!branchKey) return schema;
-
-  const branches = schema[branchKey];
-  if (!Array.isArray(branches) || branches.length === 0) return schema;
-
-  const siblings = { ...schema };
-  delete siblings[branchKey];
-  if (Object.keys(siblings).length === 0) return schema;
-
-  const folded = branches.map((branch: any) =>
-    mergeAllOf({ allOf: [siblings, branch] })
-  );
-
-  return { [branchKey]: folded };
-};
-
-/**
- * Recursively searches for a property in a schema, including nested
- * oneOf, anyOf, and allOf structures. This is needed for discriminators
- * where the property definition may be in a nested schema.
- */
-const findProperty = (
-  schema: SchemaObject,
-  propertyName: string
-): SchemaObject | undefined => {
-  // Check direct properties first
-  if (schema.properties?.[propertyName]) {
-    return schema.properties[propertyName];
-  }
-
-  // Search in oneOf schemas
-  if (schema.oneOf) {
-    for (const subschema of schema.oneOf) {
-      const found = findProperty(subschema as SchemaObject, propertyName);
-      if (found) return found;
-    }
-  }
-
-  // Search in anyOf schemas
-  if (schema.anyOf) {
-    for (const subschema of schema.anyOf) {
-      const found = findProperty(subschema as SchemaObject, propertyName);
-      if (found) return found;
-    }
-  }
-
-  // Search in allOf schemas
-  if (schema.allOf) {
-    for (const subschema of schema.allOf) {
-      const found = findProperty(subschema as SchemaObject, propertyName);
-      if (found) return found;
-    }
-  }
-
-  return undefined;
-};
-
-/**
- * Recursively searches for a discriminator in a schema, including nested
- * oneOf, anyOf, and allOf structures.
- */
-const findDiscriminator = (schema: SchemaObject): any | undefined => {
-  if (schema.discriminator) {
-    return schema.discriminator;
-  }
-
-  if (schema.oneOf) {
-    for (const subschema of schema.oneOf) {
-      const found = findDiscriminator(subschema as SchemaObject);
-      if (found) return found;
-    }
-  }
-
-  if (schema.anyOf) {
-    for (const subschema of schema.anyOf) {
-      const found = findDiscriminator(subschema as SchemaObject);
-      if (found) return found;
-    }
-  }
-
-  if (schema.allOf) {
-    for (const subschema of schema.allOf) {
-      const found = findDiscriminator(subschema as SchemaObject);
-      if (found) return found;
-    }
-  }
-
-  return undefined;
-};
-
 interface MarkdownProps {
   text: string | undefined;
 }
@@ -388,6 +216,11 @@ const AnyOneOf: React.FC<SchemaProps> = ({
               label={label}
               value={`${uniqueId}-${index}-item`}
             >
+              {anyOneSchema.description && (
+                <div style={{ marginLeft: "1rem" }}>
+                  <MarkdownWrapper text={anyOneSchema.description} />
+                </div>
+              )}
               {/* Handle primitive types directly */}
               {(isPrimitive(anyOneSchema) || anyOneSchema.const) && (
                 <SchemaItem
@@ -571,6 +404,13 @@ const PropertyDiscriminator: React.FC<SchemaEdgeProps> = ({
                 label={key}
                 value={`${index}-item-discriminator`}
               >
+                {discriminator.mapping[key]?.description && (
+                  <div style={{ marginLeft: "1rem" }}>
+                    <MarkdownWrapper
+                      text={discriminator.mapping[key].description}
+                    />
+                  </div>
+                )}
                 <SchemaNode
                   schema={discriminator.mapping[key]}
                   schemaType={schemaType}
@@ -616,9 +456,11 @@ const DiscriminatorNode: React.FC<DiscriminatorNodeProps> = ({
   let discriminatedSchemas: any = {};
   let inferredMapping: any = {};
 
-  // Search for the discriminator property in the schema, including nested structures
+  // Search for the discriminator property in the schema, including nested
+  // structures. Cached recursive lookup replaces the O(subtree) findProperty
+  // walk that caused #1525's O(N^2) render cost.
   const discriminatorProperty =
-    findProperty(schema, discriminator.propertyName) ?? {};
+    findPropertyDeep(schema, discriminator.propertyName) ?? {};
 
   if (schema.allOf) {
     const mergedSchemas = mergeAllOf(schema) as SchemaObject;
@@ -699,6 +541,20 @@ const AdditionalProperties: React.FC<SchemaProps> = ({
 
   if (!additionalProperties) return null;
 
+  if (isCircularMarker(additionalProperties)) {
+    return (
+      <SchemaItem
+        name="property name*"
+        required={false}
+        schemaName={additionalProperties}
+        schema={additionalProperties}
+        collapsible={false}
+        discriminator={false}
+        children={null}
+      />
+    );
+  }
+
   // Handle free-form objects
   if (additionalProperties === true || isEmpty(additionalProperties)) {
     return (
@@ -812,6 +668,23 @@ const Items: React.FC<{
   schemaType: "request" | "response";
   schemaPath?: string;
 }> = ({ schema, schemaType, schemaPath }) => {
+  if (isCircularMarker(schema.items)) {
+    return (
+      <div style={{ marginLeft: ".5rem" }}>
+        <OpeningArrayBracket />
+        <SchemaItem
+          collapsible={false}
+          name=""
+          schemaName={schema.items}
+          schema={schema.items}
+          discriminator={false}
+          children={null}
+        />
+        <ClosingArrayBracket />
+      </div>
+    );
+  }
+
   // Process schema.items to handle allOf merging
   let itemsSchema = schema.items;
   if (schema.items?.allOf) {
@@ -932,6 +805,20 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
     return null;
   }
 
+  if (isCircularMarker(schema)) {
+    return (
+      <SchemaItem
+        collapsible={false}
+        name={name}
+        required={Array.isArray(required) ? required.includes(name) : required}
+        schemaName={schema}
+        schema={schema}
+        discriminator={false}
+        children={null}
+      />
+    );
+  }
+
   const schemaName = getSchemaName(schema);
 
   if (discriminator && discriminator.propertyName === name) {
@@ -1018,6 +905,20 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
     );
   }
 
+  if (isCircularMarker(schema.items)) {
+    return (
+      <SchemaNodeDetails
+        name={name}
+        schemaName={schemaName}
+        required={required}
+        nullable={schema.nullable}
+        schema={schema}
+        schemaType={schemaType}
+        schemaPath={schemaPath}
+      />
+    );
+  }
+
   if (schema.allOf) {
     // handle circular properties
     if (
@@ -1176,10 +1077,12 @@ function renderChildren(
 }
 
 const SchemaNode: React.FC<SchemaProps> = ({
-  schema,
+  schema: rawSchema,
   schemaType,
   schemaPath,
 }) => {
+  const schema = useMemo(() => normalizeSchema(rawSchema), [rawSchema]);
+
   if (
     (schemaType === "request" && schema.readOnly) ||
     (schemaType === "response" && schema.writeOnly)
@@ -1188,10 +1091,11 @@ const SchemaNode: React.FC<SchemaProps> = ({
   }
 
   // Resolve discriminator recursively so nested oneOf/anyOf/allOf compositions
-  // can still render discriminator tabs.
+  // can still render discriminator tabs. Cached via getDiscriminator so per-
+  // render cost is O(1) amortized (see #1525).
   let workingSchema = schema;
   const resolvedDiscriminator =
-    schema.discriminator ?? findDiscriminator(schema);
+    schema.discriminator ?? getDiscriminator(schema);
   if (schema.allOf && !schema.discriminator && resolvedDiscriminator) {
     workingSchema = mergeAllOf(schema) as SchemaObject;
   }