docusaurus-theme-openapi-docs 4.5.1 → 4.7.0

package/src/theme/Schema/index.tsx

@@ -5,8 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import React from "react";
+import React, { useCallback } from "react";
 
+import { translate } from "@docusaurus/Translate";
+import { setSchemaSelection } from "@theme/ApiExplorer/SchemaSelection/slice";
+import { useTypedDispatch } from "@theme/ApiItem/hooks";
 import { ClosingArrayBracket, OpeningArrayBracket } from "@theme/ArrayBrackets";
 import Details from "@theme/Details";
 import DiscriminatorTabs from "@theme/DiscriminatorTabs";
@@ -14,6 +17,7 @@ import Markdown from "@theme/Markdown";
 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";
@@ -89,12 +93,29 @@ const Summary: React.FC<SummaryProps> = ({
         {(isRequired || deprecated || nullable) && (
           <span className="openapi-schema__divider" />
         )}
-        {nullable && <span className="openapi-schema__nullable">nullable</span>}
+        {nullable && (
+          <span className="openapi-schema__nullable">
+            {translate({
+              id: OPENAPI_SCHEMA_ITEM.NULLABLE,
+              message: "nullable",
+            })}
+          </span>
+        )}
         {isRequired && (
-          <span className="openapi-schema__required">required</span>
+          <span className="openapi-schema__required">
+            {translate({
+              id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+              message: "required",
+            })}
+          </span>
         )}
         {deprecated && (
-          <span className="openapi-schema__deprecated">deprecated</span>
+          <span className="openapi-schema__deprecated">
+            {translate({
+              id: OPENAPI_SCHEMA_ITEM.DEPRECATED,
+              message: "deprecated",
+            })}
+          </span>
         )}
       </span>
     </summary>
@@ -105,31 +126,102 @@ const Summary: React.FC<SummaryProps> = ({
 interface SchemaProps {
   schema: SchemaObject;
   schemaType: "request" | "response";
+  /**
+   * Optional path identifier for tracking anyOf/oneOf selections.
+   * When provided, tab selections will be dispatched to Redux state
+   * to enable dynamic body example updates.
+   */
+  schemaPath?: string;
 }
 
-const AnyOneOf: React.FC<SchemaProps> = ({ schema, schemaType }) => {
-  const type = schema.oneOf ? "oneOf" : "anyOf";
+const AnyOneOf: React.FC<SchemaProps> = ({
+  schema,
+  schemaType,
+  schemaPath,
+}) => {
+  const key = schema.oneOf ? "oneOf" : "anyOf";
+  const type = schema.oneOf
+    ? translate({ id: OPENAPI_SCHEMA_ITEM.ONE_OF, message: "oneOf" })
+    : translate({ id: OPENAPI_SCHEMA_ITEM.ANY_OF, message: "anyOf" });
+
+  // Generate a unique ID for this anyOf/oneOf to prevent tab value collisions
+  const uniqueId = React.useMemo(
+    () => Math.random().toString(36).substring(7),
+    []
+  );
+
+  // Try to get Redux dispatch - will be undefined if not inside a Provider
+  let dispatch: ReturnType<typeof useTypedDispatch> | undefined;
+  try {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    dispatch = useTypedDispatch();
+  } catch {
+    // Not inside a Redux Provider, which is fine for response schemas
+    dispatch = undefined;
+  }
+
+  // Handle tab change - dispatch to Redux if schemaPath is provided
+  const handleTabChange = useCallback(
+    (index: number) => {
+      if (schemaPath && dispatch) {
+        dispatch(setSchemaSelection({ path: schemaPath, index }));
+      }
+    },
+    [schemaPath, dispatch]
+  );
+
   return (
     <>
       <span className="badge badge--info" style={{ marginBottom: "1rem" }}>
         {type}
       </span>
-      <SchemaTabs>
-        {schema[type]?.map((anyOneSchema: any, index: number) => {
-          const label = anyOneSchema.title || anyOneSchema.type;
+      <SchemaTabs
+        groupId={`schema-${uniqueId}`}
+        lazy
+        onChange={handleTabChange}
+      >
+        {schema[key]?.map((anyOneSchema: any, index: number) => {
+          // Use getSchemaName to include format info (e.g., "string<date-time>")
+          const computedSchemaName = getSchemaName(anyOneSchema);
+
+          // Determine label for the tab
+          // Prefer explicit title, then computed schema name, then raw type
+          let label =
+            anyOneSchema.title || computedSchemaName || anyOneSchema.type;
+          if (!label) {
+            if (anyOneSchema.oneOf) {
+              label = translate({
+                id: OPENAPI_SCHEMA_ITEM.ONE_OF,
+                message: "oneOf",
+              });
+            } else if (anyOneSchema.anyOf) {
+              label = translate({
+                id: OPENAPI_SCHEMA_ITEM.ANY_OF,
+                message: "anyOf",
+              });
+            } else {
+              label = `Option ${index + 1}`;
+            }
+          }
+
+          // Build the nested schemaPath for child anyOf/oneOf
+          const childSchemaPath = schemaPath
+            ? `${schemaPath}.${index}`
+            : undefined;
+
           return (
             // @ts-ignore
             <TabItem
               key={index}
               label={label}
-              value={`${index}-item-properties`}
+              value={`${uniqueId}-${index}-item`}
             >
               {/* Handle primitive types directly */}
               {(isPrimitive(anyOneSchema) || anyOneSchema.const) && (
                 <SchemaItem
                   collapsible={false}
                   name={undefined}
-                  schemaName={anyOneSchema.type}
+                  schemaName={computedSchemaName}
                   qualifierMessage={getQualifierMessage(anyOneSchema)}
                   schema={anyOneSchema}
                   discriminator={false}
@@ -146,7 +238,7 @@ const AnyOneOf: React.FC<SchemaProps> = ({ schema, schemaType }) => {
                   <SchemaItem
                     collapsible={false}
                     name={undefined}
-                    schemaName={anyOneSchema.type}
+                    schemaName={computedSchemaName}
                     qualifierMessage={getQualifierMessage(anyOneSchema)}
                     schema={anyOneSchema}
                     discriminator={false}
@@ -155,20 +247,42 @@ const AnyOneOf: React.FC<SchemaProps> = ({ schema, schemaType }) => {
                 )}
 
               {/* Handle actual object types with properties or nested schemas */}
-              {anyOneSchema.type === "object" && anyOneSchema.properties && (
-                <Properties schema={anyOneSchema} schemaType={schemaType} />
-              )}
+              {/* Note: In OpenAPI, properties implies type: object even if not explicitly set */}
+              {(anyOneSchema.type === "object" || !anyOneSchema.type) &&
+                anyOneSchema.properties && (
+                  <Properties
+                    schema={anyOneSchema}
+                    schemaType={schemaType}
+                    schemaPath={childSchemaPath}
+                  />
+                )}
               {anyOneSchema.allOf && (
-                <SchemaNode schema={anyOneSchema} schemaType={schemaType} />
+                <SchemaNode
+                  schema={anyOneSchema}
+                  schemaType={schemaType}
+                  schemaPath={childSchemaPath}
+                />
               )}
               {anyOneSchema.oneOf && (
-                <SchemaNode schema={anyOneSchema} schemaType={schemaType} />
+                <SchemaNode
+                  schema={anyOneSchema}
+                  schemaType={schemaType}
+                  schemaPath={childSchemaPath}
+                />
               )}
               {anyOneSchema.anyOf && (
-                <SchemaNode schema={anyOneSchema} schemaType={schemaType} />
+                <SchemaNode
+                  schema={anyOneSchema}
+                  schemaType={schemaType}
+                  schemaPath={childSchemaPath}
+                />
               )}
               {anyOneSchema.items && (
-                <Items schema={anyOneSchema} schemaType={schemaType} />
+                <Items
+                  schema={anyOneSchema}
+                  schemaType={schemaType}
+                  schemaPath={childSchemaPath}
+                />
               )}
             </TabItem>
           );
@@ -178,7 +292,11 @@ const AnyOneOf: React.FC<SchemaProps> = ({ schema, schemaType }) => {
   );
 };
 
-const Properties: React.FC<SchemaProps> = ({ schema, schemaType }) => {
+const Properties: React.FC<SchemaProps> = ({
+  schema,
+  schemaType,
+  schemaPath,
+}) => {
   const discriminator = schema.discriminator;
   if (discriminator && !discriminator.mapping) {
     const anyOneOf = schema.oneOf ?? schema.anyOf ?? {};
@@ -222,6 +340,7 @@ const Properties: React.FC<SchemaProps> = ({ schema, schemaType }) => {
             }
             discriminator={discriminator}
             schemaType={schemaType}
+            schemaPath={schemaPath ? `${schemaPath}.${key}` : undefined}
           />
         )
       )}
@@ -254,7 +373,12 @@ const PropertyDiscriminator: React.FC<SchemaEdgeProps> = ({
             )}
             {required && <span className="openapi-schema__divider"></span>}
             {required && (
-              <span className="openapi-schema__required">required</span>
+              <span className="openapi-schema__required">
+                {translate({
+                  id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                  message: "required",
+                })}
+              </span>
             )}
           </span>
           <div style={{ marginLeft: "1rem" }}>
@@ -474,6 +598,7 @@ const SchemaNodeDetails: React.FC<SchemaEdgeProps> = ({
   schema,
   required,
   schemaType,
+  schemaPath,
 }) => {
   return (
     <SchemaItem collapsible={true}>
@@ -493,7 +618,11 @@ const SchemaNodeDetails: React.FC<SchemaEdgeProps> = ({
           {getQualifierMessage(schema) && (
             <MarkdownWrapper text={getQualifierMessage(schema)} />
           )}
-          <SchemaNode schema={schema} schemaType={schemaType} />
+          <SchemaNode
+            schema={schema}
+            schemaType={schemaType}
+            schemaPath={schemaPath}
+          />
         </div>
       </Details>
     </SchemaItem>
@@ -503,7 +632,8 @@ const SchemaNodeDetails: React.FC<SchemaEdgeProps> = ({
 const Items: React.FC<{
   schema: any;
   schemaType: "request" | "response";
-}> = ({ schema, schemaType }) => {
+  schemaPath?: string;
+}> = ({ schema, schemaType, schemaPath }) => {
   // Process schema.items to handle allOf merging
   let itemsSchema = schema.items;
   if (schema.items?.allOf) {
@@ -515,15 +645,26 @@ const Items: React.FC<{
   const hasProperties = itemsSchema?.properties;
   const hasAdditionalProperties = itemsSchema?.additionalProperties;
 
+  // Build the items schema path
+  const itemsSchemaPath = schemaPath ? `${schemaPath}.items` : undefined;
+
   if (hasOneOfAnyOf || hasProperties || hasAdditionalProperties) {
     return (
       <>
         <OpeningArrayBracket />
         {hasOneOfAnyOf && (
-          <AnyOneOf schema={itemsSchema} schemaType={schemaType} />
+          <AnyOneOf
+            schema={itemsSchema}
+            schemaType={schemaType}
+            schemaPath={itemsSchemaPath}
+          />
         )}
         {hasProperties && (
-          <Properties schema={itemsSchema} schemaType={schemaType} />
+          <Properties
+            schema={itemsSchema}
+            schemaType={schemaType}
+            schemaPath={itemsSchemaPath}
+          />
         )}
         {hasAdditionalProperties && (
           <AdditionalProperties schema={itemsSchema} schemaType={schemaType} />
@@ -588,6 +729,7 @@ interface SchemaEdgeProps {
   nullable?: boolean | undefined;
   discriminator?: any;
   schemaType: "request" | "response";
+  schemaPath?: string;
 }
 
 const SchemaEdge: React.FC<SchemaEdgeProps> = ({
@@ -596,6 +738,7 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
   required,
   discriminator,
   schemaType,
+  schemaPath,
 }) => {
   if (
     (schemaType === "request" && schema.readOnly) ||
@@ -629,6 +772,7 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
         required={required}
         schema={schema}
         nullable={schema.nullable}
+        schemaPath={schemaPath}
       />
     );
   }
@@ -642,6 +786,7 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
         required={required}
         schema={schema}
         nullable={schema.nullable}
+        schemaPath={schemaPath}
       />
     );
   }
@@ -655,6 +800,7 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
         required={required}
         schema={schema}
         nullable={schema.nullable}
+        schemaPath={schemaPath}
       />
     );
   }
@@ -668,11 +814,12 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
         nullable={schema.nullable}
         schema={schema}
         schemaType={schemaType}
+        schemaPath={schemaPath}
       />
     );
   }
 
-  if (schema.items?.anyOf || schema.items?.oneOf) {
+  if (schema.items?.anyOf || schema.items?.oneOf || schema.items?.allOf) {
     return (
       <SchemaNodeDetails
         name={name}
@@ -681,6 +828,7 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
         nullable={schema.nullable}
         schema={schema}
         schemaType={schemaType}
+        schemaPath={schemaPath}
       />
     );
   }
@@ -725,13 +873,12 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
           name={name}
           schemaName={mergedSchemaName}
           required={
-            Array.isArray(mergedSchemas.required)
-              ? mergedSchemas.required.includes(name)
-              : mergedSchemas.required
+            Array.isArray(required) ? required.includes(name) : required
           }
           nullable={mergedSchemas.nullable}
           schema={mergedSchemas}
           schemaType={schemaType}
+          schemaPath={schemaPath}
         />
       );
     }
@@ -742,30 +889,30 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
           name={name}
           schemaName={mergedSchemaName}
           required={
-            Array.isArray(mergedSchemas.required)
-              ? mergedSchemas.required.includes(name)
-              : mergedSchemas.required
+            Array.isArray(required) ? required.includes(name) : required
           }
           nullable={mergedSchemas.nullable}
           schema={mergedSchemas}
           schemaType={schemaType}
+          schemaPath={schemaPath}
         />
       );
     }
 
     if (mergedSchemas.items?.properties) {
-      <SchemaNodeDetails
-        name={name}
-        schemaName={mergedSchemaName}
-        required={
-          Array.isArray(mergedSchemas.required)
-            ? mergedSchemas.required.includes(name)
-            : mergedSchemas.required
-        }
-        nullable={mergedSchemas.nullable}
-        schema={mergedSchemas}
-        schemaType={schemaType}
-      />;
+      return (
+        <SchemaNodeDetails
+          name={name}
+          schemaName={mergedSchemaName}
+          required={
+            Array.isArray(required) ? required.includes(name) : required
+          }
+          nullable={mergedSchemas.nullable}
+          schema={mergedSchemas}
+          schemaType={schemaType}
+          schemaPath={schemaPath}
+        />
+      );
     }
 
     return (
@@ -798,24 +945,51 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
 
 function renderChildren(
   schema: SchemaObject,
-  schemaType: "request" | "response"
+  schemaType: "request" | "response",
+  schemaPath?: string
 ) {
   return (
     <>
-      {schema.oneOf && <AnyOneOf schema={schema} schemaType={schemaType} />}
-      {schema.anyOf && <AnyOneOf schema={schema} schemaType={schemaType} />}
+      {schema.oneOf && (
+        <AnyOneOf
+          schema={schema}
+          schemaType={schemaType}
+          schemaPath={schemaPath}
+        />
+      )}
+      {schema.anyOf && (
+        <AnyOneOf
+          schema={schema}
+          schemaType={schemaType}
+          schemaPath={schemaPath}
+        />
+      )}
       {schema.properties && (
-        <Properties schema={schema} schemaType={schemaType} />
+        <Properties
+          schema={schema}
+          schemaType={schemaType}
+          schemaPath={schemaPath}
+        />
       )}
       {schema.additionalProperties && (
         <AdditionalProperties schema={schema} schemaType={schemaType} />
       )}
-      {schema.items && <Items schema={schema} schemaType={schemaType} />}
+      {schema.items && (
+        <Items
+          schema={schema}
+          schemaType={schemaType}
+          schemaPath={schemaPath}
+        />
+      )}
     </>
   );
 }
 
-const SchemaNode: React.FC<SchemaProps> = ({ schema, schemaType }) => {
+const SchemaNode: React.FC<SchemaProps> = ({
+  schema,
+  schemaType,
+  schemaPath,
+}) => {
   if (
     (schemaType === "request" && schema.readOnly) ||
     (schemaType === "response" && schema.writeOnly)
@@ -836,6 +1010,63 @@ const SchemaNode: React.FC<SchemaProps> = ({ schema, schemaType }) => {
 
   // Handle allOf, oneOf, anyOf without discriminators
   if (schema.allOf) {
+    // Check if allOf contains multiple oneOf/anyOf items that should be rendered separately
+    const oneOfItems = schema.allOf.filter(
+      (item: any) => item.oneOf || item.anyOf
+    );
+    const hasMultipleChoices = oneOfItems.length > 1;
+
+    if (hasMultipleChoices) {
+      // Render each oneOf/anyOf constraint first, then shared properties
+      const mergedSchemas = mergeAllOf(schema) as SchemaObject;
+
+      if (
+        (schemaType === "request" && mergedSchemas.readOnly) ||
+        (schemaType === "response" && mergedSchemas.writeOnly)
+      ) {
+        return null;
+      }
+
+      return (
+        <div>
+          {/* Render all oneOf/anyOf constraints first */}
+          {schema.allOf.map((item: any, index: number) => {
+            if (item.oneOf || item.anyOf) {
+              const itemSchemaPath = schemaPath
+                ? `${schemaPath}.allOf.${index}`
+                : undefined;
+              return (
+                <div key={index}>
+                  <AnyOneOf
+                    schema={item}
+                    schemaType={schemaType}
+                    schemaPath={itemSchemaPath}
+                  />
+                </div>
+              );
+            }
+            return null;
+          })}
+          {/* Then render shared properties from the merge */}
+          {mergedSchemas.properties && (
+            <Properties
+              schema={mergedSchemas}
+              schemaType={schemaType}
+              schemaPath={schemaPath}
+            />
+          )}
+          {mergedSchemas.items && (
+            <Items
+              schema={mergedSchemas}
+              schemaType={schemaType}
+              schemaPath={schemaPath}
+            />
+          )}
+        </div>
+      );
+    }
+
+    // For other allOf cases, use standard merge behavior
     const mergedSchemas = mergeAllOf(schema) as SchemaObject;
 
     if (
@@ -848,16 +1079,32 @@ const SchemaNode: React.FC<SchemaProps> = ({ schema, schemaType }) => {
     return (
       <div>
         {mergedSchemas.oneOf && (
-          <AnyOneOf schema={mergedSchemas} schemaType={schemaType} />
+          <AnyOneOf
+            schema={mergedSchemas}
+            schemaType={schemaType}
+            schemaPath={schemaPath}
+          />
         )}
         {mergedSchemas.anyOf && (
-          <AnyOneOf schema={mergedSchemas} schemaType={schemaType} />
+          <AnyOneOf
+            schema={mergedSchemas}
+            schemaType={schemaType}
+            schemaPath={schemaPath}
+          />
         )}
         {mergedSchemas.properties && (
-          <Properties schema={mergedSchemas} schemaType={schemaType} />
+          <Properties
+            schema={mergedSchemas}
+            schemaType={schemaType}
+            schemaPath={schemaPath}
+          />
         )}
         {mergedSchemas.items && (
-          <Items schema={mergedSchemas} schemaType={schemaType} />
+          <Items
+            schema={mergedSchemas}
+            schemaType={schemaType}
+            schemaPath={schemaPath}
+          />
         )}
       </div>
     );
@@ -888,7 +1135,7 @@ const SchemaNode: React.FC<SchemaProps> = ({ schema, schemaType }) => {
     );
   }
 
-  return renderChildren(schema, schemaType);
+  return renderChildren(schema, schemaType, schemaPath);
 };
 
 export default SchemaNode;
@@ -904,5 +1151,10 @@ const PRIMITIVE_TYPES: Record<PrimitiveSchemaType, true> = {
 } as const;
 
 const isPrimitive = (schema: SchemaObject) => {
+  // Enum-only schemas (without explicit type) should be treated as primitives
+  // This is valid JSON Schema where enum values define the constraints
+  if (schema.enum && !schema.type) {
+    return true;
+  }
   return PRIMITIVE_TYPES[schema.type as PrimitiveSchemaType];
 };