docusaurus-theme-openapi-docs 5.0.2 → 5.1.1

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,105 +14,28 @@ 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,
+  useSchemaExpansion,
+} from "@theme/SchemaExpansion";
 import SchemaItem from "@theme/SchemaItem";
 import SchemaTabs from "@theme/SchemaTabs";
 import TabItem from "@theme/TabItem";
-import { OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
-// 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");
-
-const mergeAllOf = (allOf: any) => {
-  const onMergeError = (msg: string) => {
-    console.warn(msg);
-  };
-
-  const mergedSchemas = 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: 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;
 }
@@ -165,7 +88,7 @@ const Summary: React.FC<SummaryProps> = ({
         {nullable && (
           <span className="openapi-schema__nullable">
             {translate({
-              id: OPENAPI_SCHEMA_ITEM.NULLABLE,
+              id: "theme.openapi.schemaItem.nullable",
               message: "nullable",
             })}
           </span>
@@ -173,7 +96,7 @@ const Summary: React.FC<SummaryProps> = ({
         {isRequired && (
           <span className="openapi-schema__required">
             {translate({
-              id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+              id: "theme.openapi.schemaItem.required",
               message: "required",
             })}
           </span>
@@ -181,7 +104,7 @@ const Summary: React.FC<SummaryProps> = ({
         {deprecated && (
           <span className="openapi-schema__deprecated">
             {translate({
-              id: OPENAPI_SCHEMA_ITEM.DEPRECATED,
+              id: "theme.openapi.schemaItem.deprecated",
               message: "deprecated",
             })}
           </span>
@@ -218,8 +141,8 @@ const AnyOneOf: React.FC<SchemaProps> = ({
   }
 
   const type = schema.oneOf
-    ? translate({ id: OPENAPI_SCHEMA_ITEM.ONE_OF, message: "oneOf" })
-    : translate({ id: OPENAPI_SCHEMA_ITEM.ANY_OF, message: "anyOf" });
+    ? translate({ id: "theme.openapi.schemaItem.oneOf", message: "oneOf" })
+    : translate({ id: "theme.openapi.schemaItem.anyOf", message: "anyOf" });
 
   // Generate a unique ID for this anyOf/oneOf to prevent tab value collisions
   const uniqueId = React.useMemo(
@@ -268,12 +191,12 @@ const AnyOneOf: React.FC<SchemaProps> = ({
           if (!label) {
             if (anyOneSchema.oneOf) {
               label = translate({
-                id: OPENAPI_SCHEMA_ITEM.ONE_OF,
+                id: "theme.openapi.schemaItem.oneOf",
                 message: "oneOf",
               });
             } else if (anyOneSchema.anyOf) {
               label = translate({
-                id: OPENAPI_SCHEMA_ITEM.ANY_OF,
+                id: "theme.openapi.schemaItem.anyOf",
                 message: "anyOf",
               });
             } else {
@@ -293,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
@@ -454,7 +382,7 @@ const PropertyDiscriminator: React.FC<SchemaEdgeProps> = ({
             {required && (
               <span className="openapi-schema__required">
                 {translate({
-                  id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                  id: "theme.openapi.schemaItem.required",
                   message: "required",
                 })}
               </span>
@@ -476,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}
@@ -521,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;
@@ -604,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 (
@@ -676,10 +627,15 @@ const SchemaNodeDetails: React.FC<SchemaEdgeProps> = ({
   schemaType,
   schemaPath,
 }) => {
+  const depth = useSchemaDepth();
+  const { level } = useSchemaExpansion();
+  const defaultOpen = depth < level;
   return (
     <SchemaItem collapsible={true}>
       <Details
+        key={`level-${level}`}
         className="openapi-markdown__details"
+        open={defaultOpen}
         summary={
           <Summary
             name={name}
@@ -694,11 +650,13 @@ const SchemaNodeDetails: React.FC<SchemaEdgeProps> = ({
           {getQualifierMessage(schema) && (
             <MarkdownWrapper text={getQualifierMessage(schema)} />
           )}
-          <SchemaNode
-            schema={schema}
-            schemaType={schemaType}
-            schemaPath={schemaPath}
-          />
+          <SchemaDepthProvider depth={depth + 1}>
+            <SchemaNode
+              schema={schema}
+              schemaType={schemaType}
+              schemaPath={schemaPath}
+            />
+          </SchemaDepthProvider>
         </div>
       </Details>
     </SchemaItem>
@@ -710,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) {
@@ -725,17 +700,25 @@ const Items: React.FC<{
   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
+        ? foldSiblingsIntoBranches(itemsSchema)
+        : itemsSchema;
+    const renderHasProperties =
+      hasOneOfAnyOf && hasProperties ? false : hasProperties;
     return (
       <>
         <OpeningArrayBracket />
         {hasOneOfAnyOf && (
           <AnyOneOf
-            schema={itemsSchema}
+            schema={renderSchema}
             schemaType={schemaType}
             schemaPath={itemsSchemaPath}
           />
         )}
-        {hasProperties && (
+        {renderHasProperties && (
           <Properties
             schema={itemsSchema}
             schemaType={schemaType}
@@ -822,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) {
@@ -908,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 (
@@ -1020,23 +1031,31 @@ function renderChildren(
   schemaType: "request" | "response",
   schemaPath?: string
 ) {
+  // 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 ? foldSiblingsIntoBranches(schema) : schema;
+  const renderProperties =
+    hasOneOfAnyOf && hasProperties ? false : hasProperties;
   return (
     <>
-      {schema.oneOf && (
+      {folded.oneOf && (
         <AnyOneOf
-          schema={schema}
+          schema={folded}
           schemaType={schemaType}
           schemaPath={schemaPath}
         />
       )}
-      {schema.anyOf && (
+      {folded.anyOf && (
         <AnyOneOf
-          schema={schema}
+          schema={folded}
           schemaType={schemaType}
           schemaPath={schemaPath}
         />
       )}
-      {schema.properties && (
+      {renderProperties && (
         <Properties
           schema={schema}
           schemaType={schemaType}
@@ -1058,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)
@@ -1070,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;
   }
@@ -1160,23 +1182,34 @@ const SchemaNode: React.FC<SchemaProps> = ({
       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
+        ? foldSiblingsIntoBranches(mergedSchemas)
+        : mergedSchemas;
+    const renderProperties =
+      hasOneOfAnyOf && hasProperties ? false : hasProperties;
+
     return (
       <div>
-        {mergedSchemas.oneOf && (
+        {folded.oneOf && (
           <AnyOneOf
-            schema={mergedSchemas}
+            schema={folded}
             schemaType={schemaType}
             schemaPath={schemaPath}
           />
         )}
-        {mergedSchemas.anyOf && (
+        {folded.anyOf && (
           <AnyOneOf
-            schema={mergedSchemas}
+            schema={folded}
             schemaType={schemaType}
             schemaPath={schemaPath}
           />
         )}
-        {mergedSchemas.properties && (
+        {renderProperties && (
           <Properties
             schema={mergedSchemas}
             schemaType={schemaType}