docusaurus-theme-openapi-docs 5.0.2 → 5.1.1

package/lib/theme/ResponseSchema/index.js

@@ -19,10 +19,10 @@ const Markdown_1 = __importDefault(require("@theme/Markdown"));
 const MimeTabs_1 = __importDefault(require("@theme/MimeTabs")); // Assume these components exist
 const ResponseExamples_1 = require("@theme/ResponseExamples");
 const Schema_1 = __importDefault(require("@theme/Schema"));
+const SchemaExpansion_1 = __importDefault(require("@theme/SchemaExpansion"));
 const SchemaTabs_1 = __importDefault(require("@theme/SchemaTabs"));
 const SkeletonLoader_1 = __importDefault(require("@theme/SkeletonLoader"));
 const TabItem_1 = __importDefault(require("@theme/TabItem"));
-const translationIds_1 = require("@theme/translationIds");
 const ResponseSchemaComponent = ({ title, body, style }) => {
   if (
     body === undefined ||
@@ -57,7 +57,7 @@ const ResponseSchemaComponent = ({ title, body, style }) => {
                 "div",
                 null,
                 (0, Translate_1.translate)({
-                  id: translationIds_1.OPENAPI_SCHEMA.NO_SCHEMA,
+                  id: "theme.openapi.schema.noSchema",
                   message: "No schema",
                 })
               )
@@ -83,29 +83,31 @@ const ResponseSchemaComponent = ({ title, body, style }) => {
                     open: true,
                     style: style,
                     summary: react_1.default.createElement(
-                      react_1.default.Fragment,
-                      null,
+                      "summary",
+                      {
+                        className:
+                          "openapi-markdown__details-summary--with-control",
+                      },
                       react_1.default.createElement(
-                        "summary",
-                        null,
-                        react_1.default.createElement(
-                          "strong",
-                          {
-                            className:
-                              "openapi-markdown__details-summary-response",
-                          },
-                          title,
-                          body.required === true &&
-                            react_1.default.createElement(
-                              "span",
-                              { className: "openapi-schema__required" },
-                              (0, Translate_1.translate)({
-                                id: translationIds_1.OPENAPI_SCHEMA_ITEM
-                                  .REQUIRED,
-                                message: "required",
-                              })
-                            )
-                        )
+                        "strong",
+                        {
+                          className:
+                            "openapi-markdown__details-summary-response",
+                        },
+                        title,
+                        body.required === true &&
+                          react_1.default.createElement(
+                            "span",
+                            { className: "openapi-schema__required" },
+                            (0, Translate_1.translate)({
+                              id: "theme.openapi.schemaItem.required",
+                              message: "required",
+                            })
+                          )
+                      ),
+                      react_1.default.createElement(
+                        SchemaExpansion_1.default,
+                        null
                       )
                     ),
                   },

package/lib/theme/Schema/index.js

@@ -77,85 +77,14 @@ const DiscriminatorTabs_1 = __importDefault(
   require("@theme/DiscriminatorTabs")
 );
 const Markdown_1 = __importDefault(require("@theme/Markdown"));
+const normalize_1 = require("@theme/Schema/normalize");
+const SchemaExpansion_1 = require("@theme/SchemaExpansion");
 const SchemaItem_1 = __importDefault(require("@theme/SchemaItem"));
 const SchemaTabs_1 = __importDefault(require("@theme/SchemaTabs"));
 const TabItem_1 = __importDefault(require("@theme/TabItem"));
-const translationIds_1 = require("@theme/translationIds");
-// eslint-disable-next-line import/no-extraneous-dependencies
-const allof_merge_1 = require("allof-merge");
 const clsx_1 = __importDefault(require("clsx"));
 const isEmpty_1 = __importDefault(require("lodash/isEmpty"));
 const schema_1 = require("../../markdown/schema");
-// eslint-disable-next-line import/no-extraneous-dependencies
-// const jsonSchemaMergeAllOf = require("json-schema-merge-allof");
-const mergeAllOf = (allOf) => {
-  const onMergeError = (msg) => {
-    console.warn(msg);
-  };
-  const mergedSchemas = (0, allof_merge_1.merge)(allOf, { onMergeError });
-  return mergedSchemas ?? {};
-};
-/**
- * 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, propertyName) => {
-  // 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, propertyName);
-      if (found) return found;
-    }
-  }
-  // Search in anyOf schemas
-  if (schema.anyOf) {
-    for (const subschema of schema.anyOf) {
-      const found = findProperty(subschema, propertyName);
-      if (found) return found;
-    }
-  }
-  // Search in allOf schemas
-  if (schema.allOf) {
-    for (const subschema of schema.allOf) {
-      const found = findProperty(subschema, 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) => {
-  if (schema.discriminator) {
-    return schema.discriminator;
-  }
-  if (schema.oneOf) {
-    for (const subschema of schema.oneOf) {
-      const found = findDiscriminator(subschema);
-      if (found) return found;
-    }
-  }
-  if (schema.anyOf) {
-    for (const subschema of schema.anyOf) {
-      const found = findDiscriminator(subschema);
-      if (found) return found;
-    }
-  }
-  if (schema.allOf) {
-    for (const subschema of schema.allOf) {
-      const found = findDiscriminator(subschema);
-      if (found) return found;
-    }
-  }
-  return undefined;
-};
 // Renders string as markdown, useful for descriptions and qualifiers
 const MarkdownWrapper = ({ text }) => {
   return react_1.default.createElement(
@@ -199,7 +128,7 @@ const Summary = ({ name, schemaName, schema, required }) => {
           "span",
           { className: "openapi-schema__nullable" },
           (0, Translate_1.translate)({
-            id: translationIds_1.OPENAPI_SCHEMA_ITEM.NULLABLE,
+            id: "theme.openapi.schemaItem.nullable",
             message: "nullable",
           })
         ),
@@ -208,7 +137,7 @@ const Summary = ({ name, schemaName, schema, required }) => {
           "span",
           { className: "openapi-schema__required" },
           (0, Translate_1.translate)({
-            id: translationIds_1.OPENAPI_SCHEMA_ITEM.REQUIRED,
+            id: "theme.openapi.schemaItem.required",
             message: "required",
           })
         ),
@@ -217,7 +146,7 @@ const Summary = ({ name, schemaName, schema, required }) => {
           "span",
           { className: "openapi-schema__deprecated" },
           (0, Translate_1.translate)({
-            id: translationIds_1.OPENAPI_SCHEMA_ITEM.DEPRECATED,
+            id: "theme.openapi.schemaItem.deprecated",
             message: "deprecated",
           })
         )
@@ -234,11 +163,11 @@ const AnyOneOf = ({ schema, schemaType, schemaPath }) => {
   }
   const type = schema.oneOf
     ? (0, Translate_1.translate)({
-        id: translationIds_1.OPENAPI_SCHEMA_ITEM.ONE_OF,
+        id: "theme.openapi.schemaItem.oneOf",
         message: "oneOf",
       })
     : (0, Translate_1.translate)({
-        id: translationIds_1.OPENAPI_SCHEMA_ITEM.ANY_OF,
+        id: "theme.openapi.schemaItem.anyOf",
         message: "anyOf",
       });
   // Generate a unique ID for this anyOf/oneOf to prevent tab value collisions
@@ -285,12 +214,12 @@ const AnyOneOf = ({ schema, schemaType, schemaPath }) => {
         if (!label) {
           if (anyOneSchema.oneOf) {
             label = (0, Translate_1.translate)({
-              id: translationIds_1.OPENAPI_SCHEMA_ITEM.ONE_OF,
+              id: "theme.openapi.schemaItem.oneOf",
               message: "oneOf",
             });
           } else if (anyOneSchema.anyOf) {
             label = (0, Translate_1.translate)({
-              id: translationIds_1.OPENAPI_SCHEMA_ITEM.ANY_OF,
+              id: "theme.openapi.schemaItem.anyOf",
               message: "anyOf",
             });
           } else {
@@ -306,6 +235,14 @@ const AnyOneOf = ({ schema, schemaType, schemaPath }) => {
           react_1.default.createElement(
             TabItem_1.default,
             { key: index, label: label, value: `${uniqueId}-${index}-item` },
+            anyOneSchema.description &&
+              react_1.default.createElement(
+                "div",
+                { style: { marginLeft: "1rem" } },
+                react_1.default.createElement(MarkdownWrapper, {
+                  text: anyOneSchema.description,
+                })
+              ),
             (isPrimitive(anyOneSchema) || anyOneSchema.const) &&
               react_1.default.createElement(SchemaItem_1.default, {
                 collapsible: false,
@@ -459,7 +396,7 @@ const PropertyDiscriminator = ({
               "span",
               { className: "openapi-schema__required" },
               (0, Translate_1.translate)({
-                id: translationIds_1.OPENAPI_SCHEMA_ITEM.REQUIRED,
+                id: "theme.openapi.schemaItem.required",
                 message: "required",
               })
             )
@@ -484,6 +421,14 @@ const PropertyDiscriminator = ({
             react_1.default.createElement(
               TabItem_1.default,
               { key: index, label: key, value: `${index}-item-discriminator` },
+              discriminator.mapping[key]?.description &&
+                react_1.default.createElement(
+                  "div",
+                  { style: { marginLeft: "1rem" } },
+                  react_1.default.createElement(MarkdownWrapper, {
+                    text: discriminator.mapping[key].description,
+                  })
+                ),
               react_1.default.createElement(SchemaNode, {
                 schema: discriminator.mapping[key],
                 schemaType: schemaType,
@@ -513,11 +458,13 @@ const PropertyDiscriminator = ({
 const DiscriminatorNode = ({ discriminator, schema, schemaType }) => {
   let discriminatedSchemas = {};
   let inferredMapping = {};
-  // 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) ?? {};
+    (0, normalize_1.findPropertyDeep)(schema, discriminator.propertyName) ?? {};
   if (schema.allOf) {
-    const mergedSchemas = mergeAllOf(schema);
+    const mergedSchemas = (0, normalize_1.mergeAllOf)(schema);
     if (mergedSchemas.oneOf || mergedSchemas.anyOf) {
       discriminatedSchemas = mergedSchemas.oneOf || mergedSchemas.anyOf;
     }
@@ -537,7 +484,7 @@ const DiscriminatorNode = ({ discriminator, schema, schemaType }) => {
     // Handle discriminated schema with allOf
     let mergedSubSchema = {};
     if (subSchema.allOf) {
-      mergedSubSchema = mergeAllOf(subSchema);
+      mergedSubSchema = (0, normalize_1.mergeAllOf)(subSchema);
     }
     const subProperties = subSchema.properties || mergedSubSchema.properties;
     // Add a safeguard check to avoid referencing subProperties if it's undefined
@@ -578,6 +525,17 @@ const DiscriminatorNode = ({ discriminator, schema, schemaType }) => {
 const AdditionalProperties = ({ schema, schemaType }) => {
   const additionalProperties = schema.additionalProperties;
   if (!additionalProperties) return null;
+  if ((0, normalize_1.isCircularMarker)(additionalProperties)) {
+    return react_1.default.createElement(SchemaItem_1.default, {
+      name: "property name*",
+      required: false,
+      schemaName: additionalProperties,
+      schema: additionalProperties,
+      collapsible: false,
+      discriminator: false,
+      children: null,
+    });
+  }
   // Handle free-form objects
   if (
     additionalProperties === true ||
@@ -644,13 +602,18 @@ const SchemaNodeDetails = ({
   schemaType,
   schemaPath,
 }) => {
+  const depth = (0, SchemaExpansion_1.useSchemaDepth)();
+  const { level } = (0, SchemaExpansion_1.useSchemaExpansion)();
+  const defaultOpen = depth < level;
   return react_1.default.createElement(
     SchemaItem_1.default,
     { collapsible: true },
     react_1.default.createElement(
       Details_1.default,
       {
+        key: `level-${level}`,
         className: "openapi-markdown__details",
+        open: defaultOpen,
         summary: react_1.default.createElement(Summary, {
           name: name,
           schemaName: schemaName,
@@ -669,20 +632,40 @@ const SchemaNodeDetails = ({
           react_1.default.createElement(MarkdownWrapper, {
             text: (0, schema_1.getQualifierMessage)(schema),
           }),
-        react_1.default.createElement(SchemaNode, {
-          schema: schema,
-          schemaType: schemaType,
-          schemaPath: schemaPath,
-        })
+        react_1.default.createElement(
+          SchemaExpansion_1.SchemaDepthProvider,
+          { depth: depth + 1 },
+          react_1.default.createElement(SchemaNode, {
+            schema: schema,
+            schemaType: schemaType,
+            schemaPath: schemaPath,
+          })
+        )
       )
     )
   );
 };
 const Items = ({ schema, schemaType, schemaPath }) => {
+  if ((0, normalize_1.isCircularMarker)(schema.items)) {
+    return react_1.default.createElement(
+      "div",
+      { style: { marginLeft: ".5rem" } },
+      react_1.default.createElement(ArrayBrackets_1.OpeningArrayBracket, null),
+      react_1.default.createElement(SchemaItem_1.default, {
+        collapsible: false,
+        name: "",
+        schemaName: schema.items,
+        schema: schema.items,
+        discriminator: false,
+        children: null,
+      }),
+      react_1.default.createElement(ArrayBrackets_1.ClosingArrayBracket, null)
+    );
+  }
   // Process schema.items to handle allOf merging
   let itemsSchema = schema.items;
   if (schema.items?.allOf) {
-    itemsSchema = mergeAllOf(schema.items);
+    itemsSchema = (0, normalize_1.mergeAllOf)(schema.items);
   }
   // Handle complex schemas with multiple schema types
   const hasOneOfAnyOf = itemsSchema?.oneOf || itemsSchema?.anyOf;
@@ -691,17 +674,25 @@ const Items = ({ schema, schemaType, schemaPath }) => {
   // Build the items schema path
   const itemsSchemaPath = schemaPath ? `${schemaPath}.items` : undefined;
   if (hasOneOfAnyOf || hasProperties || hasAdditionalProperties) {
+    // Fold sibling properties into each oneOf/anyOf branch to avoid duplicate
+    // property rendering. See issue #1218.
+    const renderSchema =
+      hasOneOfAnyOf && hasProperties
+        ? (0, normalize_1.foldSiblingsIntoBranches)(itemsSchema)
+        : itemsSchema;
+    const renderHasProperties =
+      hasOneOfAnyOf && hasProperties ? false : hasProperties;
     return react_1.default.createElement(
       react_1.default.Fragment,
       null,
       react_1.default.createElement(ArrayBrackets_1.OpeningArrayBracket, null),
       hasOneOfAnyOf &&
         react_1.default.createElement(AnyOneOf, {
-          schema: itemsSchema,
+          schema: renderSchema,
           schemaType: schemaType,
           schemaPath: itemsSchemaPath,
         }),
-      hasProperties &&
+      renderHasProperties &&
         react_1.default.createElement(Properties, {
           schema: itemsSchema,
           schemaType: schemaType,
@@ -771,6 +762,17 @@ const SchemaEdge = ({
   ) {
     return null;
   }
+  if ((0, normalize_1.isCircularMarker)(schema)) {
+    return react_1.default.createElement(SchemaItem_1.default, {
+      collapsible: false,
+      name: name,
+      required: Array.isArray(required) ? required.includes(name) : required,
+      schemaName: schema,
+      schema: schema,
+      discriminator: false,
+      children: null,
+    });
+  }
   const schemaName = (0, schema_1.getSchemaName)(schema);
   if (discriminator && discriminator.propertyName === name) {
     return react_1.default.createElement(PropertyDiscriminator, {
@@ -838,6 +840,17 @@ const SchemaEdge = ({
       schemaPath: schemaPath,
     });
   }
+  if ((0, normalize_1.isCircularMarker)(schema.items)) {
+    return react_1.default.createElement(SchemaNodeDetails, {
+      name: name,
+      schemaName: schemaName,
+      required: required,
+      nullable: schema.nullable,
+      schema: schema,
+      schemaType: schemaType,
+      schemaPath: schemaPath,
+    });
+  }
   if (schema.allOf) {
     // handle circular properties
     if (
@@ -856,7 +869,7 @@ const SchemaEdge = ({
         children: null,
       });
     }
-    const mergedSchemas = mergeAllOf(schema);
+    const mergedSchemas = (0, normalize_1.mergeAllOf)(schema);
     if (
       (schemaType === "request" && mergedSchemas.readOnly) ||
       (schemaType === "response" && mergedSchemas.writeOnly)
@@ -918,22 +931,32 @@ const SchemaEdge = ({
   });
 };
 function renderChildren(schema, schemaType, schemaPath) {
+  // Fold sibling properties into each oneOf/anyOf branch to avoid duplicate
+  // property rendering. See issue #1218.
+  const hasOneOfAnyOf = !!(schema.oneOf || schema.anyOf);
+  const hasProperties = !!schema.properties;
+  const folded =
+    hasOneOfAnyOf && hasProperties
+      ? (0, normalize_1.foldSiblingsIntoBranches)(schema)
+      : schema;
+  const renderProperties =
+    hasOneOfAnyOf && hasProperties ? false : hasProperties;
   return react_1.default.createElement(
     react_1.default.Fragment,
     null,
-    schema.oneOf &&
+    folded.oneOf &&
       react_1.default.createElement(AnyOneOf, {
-        schema: schema,
+        schema: folded,
         schemaType: schemaType,
         schemaPath: schemaPath,
       }),
-    schema.anyOf &&
+    folded.anyOf &&
       react_1.default.createElement(AnyOneOf, {
-        schema: schema,
+        schema: folded,
         schemaType: schemaType,
         schemaPath: schemaPath,
       }),
-    schema.properties &&
+    renderProperties &&
       react_1.default.createElement(Properties, {
         schema: schema,
         schemaType: schemaType,
@@ -952,7 +975,11 @@ function renderChildren(schema, schemaType, schemaPath) {
       })
   );
 }
-const SchemaNode = ({ schema, schemaType, schemaPath }) => {
+const SchemaNode = ({ schema: rawSchema, schemaType, schemaPath }) => {
+  const schema = (0, react_1.useMemo)(
+    () => (0, normalize_1.normalizeSchema)(rawSchema),
+    [rawSchema]
+  );
   if (
     (schemaType === "request" && schema.readOnly) ||
     (schemaType === "response" && schema.writeOnly)
@@ -960,12 +987,13 @@ const SchemaNode = ({ schema, schemaType, schemaPath }) => {
     return null;
   }
   // 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 ?? (0, normalize_1.getDiscriminator)(schema);
   if (schema.allOf && !schema.discriminator && resolvedDiscriminator) {
-    workingSchema = mergeAllOf(schema);
+    workingSchema = (0, normalize_1.mergeAllOf)(schema);
   }
   if (!workingSchema.discriminator && resolvedDiscriminator) {
     workingSchema.discriminator = resolvedDiscriminator;
@@ -985,7 +1013,7 @@ const SchemaNode = ({ schema, schemaType, schemaPath }) => {
     const hasMultipleChoices = oneOfItems.length > 1;
     if (hasMultipleChoices) {
       // Render each oneOf/anyOf constraint first, then shared properties
-      const mergedSchemas = mergeAllOf(schema);
+      const mergedSchemas = (0, normalize_1.mergeAllOf)(schema);
       if (
         (schemaType === "request" && mergedSchemas.readOnly) ||
         (schemaType === "response" && mergedSchemas.writeOnly)
@@ -1027,29 +1055,39 @@ const SchemaNode = ({ schema, schemaType, schemaPath }) => {
       );
     }
     // For other allOf cases, use standard merge behavior
-    const mergedSchemas = mergeAllOf(schema);
+    const mergedSchemas = (0, normalize_1.mergeAllOf)(schema);
     if (
       (schemaType === "request" && mergedSchemas.readOnly) ||
       (schemaType === "response" && mergedSchemas.writeOnly)
     ) {
       return null;
     }
+    // Fold sibling properties into each oneOf/anyOf branch to avoid duplicate
+    // property rendering. See issue #1218.
+    const hasOneOfAnyOf = !!(mergedSchemas.oneOf || mergedSchemas.anyOf);
+    const hasProperties = !!mergedSchemas.properties;
+    const folded =
+      hasOneOfAnyOf && hasProperties
+        ? (0, normalize_1.foldSiblingsIntoBranches)(mergedSchemas)
+        : mergedSchemas;
+    const renderProperties =
+      hasOneOfAnyOf && hasProperties ? false : hasProperties;
     return react_1.default.createElement(
       "div",
       null,
-      mergedSchemas.oneOf &&
+      folded.oneOf &&
         react_1.default.createElement(AnyOneOf, {
-          schema: mergedSchemas,
+          schema: folded,
           schemaType: schemaType,
           schemaPath: schemaPath,
         }),
-      mergedSchemas.anyOf &&
+      folded.anyOf &&
         react_1.default.createElement(AnyOneOf, {
-          schema: mergedSchemas,
+          schema: folded,
           schemaType: schemaType,
           schemaPath: schemaPath,
         }),
-      mergedSchemas.properties &&
+      renderProperties &&
         react_1.default.createElement(Properties, {
           schema: mergedSchemas,
           schemaType: schemaType,

package/lib/theme/Schema/normalize.d.ts

@@ -0,0 +1,41 @@
+export declare function isCircularMarker(value: unknown): value is string;
+export declare function mergeAllOf(schema: any): any;
+/**
+ * Fold sibling fields into each oneOf/anyOf branch via allOf-merge so each
+ * branch is self-contained. See #1218.
+ *
+ * Skipped when a discriminator is present: DiscriminatorNode already renders
+ * sibling properties at the top level, and folding would duplicate the
+ * discriminator metadata into each branch (causing nested DiscriminatorNode
+ * renders inside tabs — see #1525 follow-up).
+ *
+ * Called by normalizeSchema after allOf resolution. Uses mergeAllOf internally
+ * to compose `{ allOf: [siblings, branch] }` per branch — the WeakMap caches
+ * in stripConflictingAdditionalProps prevent redundant work on shared subtrees.
+ */
+export declare function foldSiblingsIntoBranches(schema: any): any;
+export declare function getDiscriminator(schema: any): any | undefined;
+/**
+ * Cached recursive property lookup. Searches schema.properties first, then
+ * into oneOf/anyOf/allOf branches. Returns O(1) on repeated calls with the
+ * same (schema, propertyName) pair — replaces the O(subtree) findProperty
+ * walk that caused #1525's O(N^2) render cost.
+ */
+export declare function findPropertyDeep(schema: any, propertyName: string): any | undefined;
+/**
+ * Identity-stable schema pass-through. Returns the input as-is so SchemaNode
+ * useMemo dependencies stay stable across renders.
+ *
+ * Earlier iterations of this function eagerly merged allOf and folded
+ * siblings into oneOf/anyOf branches, but those operations need to stay
+ * conditional inside SchemaNode and DiscriminatorNode — eager versions
+ * caused cartesian product expansion (allOf with multiple oneOfs) and
+ * double-folding regressions. The render-time helpers below
+ * (mergeAllOf, foldSiblingsIntoBranches) are still cached via the WeakMap
+ * inside stripConflictingAdditionalProps, so per-render cost stays bounded.
+ *
+ * The perf win for #1525 comes from getDiscriminator's WeakMap cache
+ * replacing the O(subtree) findDiscriminator walk, not from eager
+ * normalization here.
+ */
+export declare function normalizeSchema(schema: any): any;