docusaurus-theme-openapi-docs 4.7.1 → 5.0.0

package/src/theme/RequestSchema/index.tsx

@@ -12,7 +12,13 @@ import { translate } from "@docusaurus/Translate";
 import Details from "@theme/Details";
 import Markdown from "@theme/Markdown";
 import MimeTabs from "@theme/MimeTabs"; // Assume these components exist
+import {
+  ExampleFromSchema,
+  ResponseExample,
+  ResponseExamples,
+} from "@theme/ResponseExamples";
 import SchemaNode from "@theme/Schema";
+import SchemaTabs from "@theme/SchemaTabs";
 import SkeletonLoader from "@theme/SkeletonLoader";
 import TabItem from "@theme/TabItem";
 import { OPENAPI_REQUEST, OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
@@ -46,7 +52,11 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
     return (
       <MimeTabs className="openapi-tabs__mime" schemaType="request" lazy>
         {mimeTypes.map((mimeType) => {
-          const firstBody = body.content![mimeType].schema;
+          const mediaTypeObject = body.content![mimeType];
+          const firstBody = mediaTypeObject?.schema;
+          const requestExamples = mediaTypeObject?.examples;
+          const requestExample = mediaTypeObject?.example;
+
           if (
             firstBody === undefined ||
             (firstBody.properties &&
@@ -57,49 +67,73 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
           return (
             // @ts-ignore
             <TabItem key={mimeType} label={mimeType} value={mimeType}>
-              <div style={{ marginTop: "1rem" }}>
-                <Details
-                  className="openapi-markdown__details mime"
-                  data-collapsed={false}
-                  open={true}
-                  style={style}
-                  summary={
-                    <>
-                      <summary>
-                        <h3 className="openapi-markdown__details-summary-header-body">
-                          {translate({
-                            id: OPENAPI_REQUEST.BODY_TITLE,
-                            message: title,
-                          })}
-                          {body.required === true && (
-                            <span className="openapi-schema__required">
+              <SchemaTabs className="openapi-tabs__schema">
+                {/* @ts-ignore */}
+                <TabItem key={title} label={title} value={title}>
+                  <div style={{ marginTop: "1rem" }}>
+                    <Details
+                      className="openapi-markdown__details mime"
+                      data-collapsed={false}
+                      open={true}
+                      style={style}
+                      summary={
+                        <>
+                          <summary>
+                            <h3 className="openapi-markdown__details-summary-header-body">
                               {translate({
-                                id: OPENAPI_SCHEMA_ITEM.REQUIRED,
-                                message: "required",
+                                id: OPENAPI_REQUEST.BODY_TITLE,
+                                message: title,
                               })}
-                            </span>
-                          )}
-                        </h3>
-                      </summary>
-                    </>
-                  }
-                >
-                  <div style={{ textAlign: "left", marginLeft: "1rem" }}>
-                    {body.description && (
-                      <div style={{ marginTop: "1rem", marginBottom: "1rem" }}>
-                        <Markdown>{body.description}</Markdown>
+                              {body.required === true && (
+                                <span className="openapi-schema__required">
+                                  {translate({
+                                    id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                                    message: "required",
+                                  })}
+                                </span>
+                              )}
+                            </h3>
+                          </summary>
+                        </>
+                      }
+                    >
+                      <div style={{ textAlign: "left", marginLeft: "1rem" }}>
+                        {body.description && (
+                          <div
+                            style={{ marginTop: "1rem", marginBottom: "1rem" }}
+                          >
+                            <Markdown>{body.description}</Markdown>
+                          </div>
+                        )}
                       </div>
-                    )}
+                      <ul style={{ marginLeft: "1rem" }}>
+                        <SchemaNode
+                          schema={firstBody}
+                          schemaType="request"
+                          schemaPath="requestBody"
+                        />
+                      </ul>
+                    </Details>
                   </div>
-                  <ul style={{ marginLeft: "1rem" }}>
-                    <SchemaNode
-                      schema={firstBody}
-                      schemaType="request"
-                      schemaPath="requestBody"
-                    />
-                  </ul>
-                </Details>
-              </div>
+                </TabItem>
+                {firstBody &&
+                  !requestExample &&
+                  !requestExamples &&
+                  ExampleFromSchema({
+                    schema: firstBody,
+                    mimeType: mimeType,
+                  })}
+                {requestExamples &&
+                  ResponseExamples({
+                    responseExamples: requestExamples,
+                    mimeType,
+                  })}
+                {requestExample &&
+                  ResponseExample({
+                    responseExample: requestExample,
+                    mimeType,
+                  })}
+              </SchemaTabs>
             </TabItem>
           );
         })}
@@ -108,8 +142,10 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
   }
 
   const randomFirstKey = mimeTypes[0];
-  const firstBody =
-    body.content[randomFirstKey].schema ?? body.content![randomFirstKey];
+  const mediaTypeObject = body.content[randomFirstKey];
+  const firstBody = mediaTypeObject?.schema ?? body.content![randomFirstKey];
+  const requestExamples = mediaTypeObject?.examples;
+  const requestExample = mediaTypeObject?.example;
 
   if (firstBody === undefined) {
     return null;
@@ -119,50 +155,72 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
     <MimeTabs className="openapi-tabs__mime" schemaType="request">
       {/* @ts-ignore */}
       <TabItem label={randomFirstKey} value={`${randomFirstKey}-schema`}>
-        <Details
-          className="openapi-markdown__details mime"
-          data-collapsed={false}
-          open={true}
-          style={style}
-          summary={
-            <>
-              <summary>
-                <h3 className="openapi-markdown__details-summary-header-body">
-                  {translate({
-                    id: OPENAPI_REQUEST.BODY_TITLE,
-                    message: title,
-                  })}
-                  {firstBody.type === "array" && (
-                    <span style={{ opacity: "0.6" }}> array</span>
-                  )}
-                  {body.required && (
-                    <strong className="openapi-schema__required">
+        <SchemaTabs className="openapi-tabs__schema">
+          {/* @ts-ignore */}
+          <TabItem key={title} label={title} value={title}>
+            <Details
+              className="openapi-markdown__details mime"
+              data-collapsed={false}
+              open={true}
+              style={style}
+              summary={
+                <>
+                  <summary>
+                    <h3 className="openapi-markdown__details-summary-header-body">
                       {translate({
-                        id: OPENAPI_SCHEMA_ITEM.REQUIRED,
-                        message: "required",
+                        id: OPENAPI_REQUEST.BODY_TITLE,
+                        message: title,
                       })}
-                    </strong>
-                  )}
-                </h3>
-              </summary>
-            </>
-          }
-        >
-          <div style={{ textAlign: "left", marginLeft: "1rem" }}>
-            {body.description && (
-              <div style={{ marginTop: "1rem", marginBottom: "1rem" }}>
-                <Markdown>{body.description}</Markdown>
+                      {firstBody.type === "array" && (
+                        <span style={{ opacity: "0.6" }}> array</span>
+                      )}
+                      {body.required && (
+                        <strong className="openapi-schema__required">
+                          {translate({
+                            id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                            message: "required",
+                          })}
+                        </strong>
+                      )}
+                    </h3>
+                  </summary>
+                </>
+              }
+            >
+              <div style={{ textAlign: "left", marginLeft: "1rem" }}>
+                {body.description && (
+                  <div style={{ marginTop: "1rem", marginBottom: "1rem" }}>
+                    <Markdown>{body.description}</Markdown>
+                  </div>
+                )}
               </div>
-            )}
-          </div>
-          <ul style={{ marginLeft: "1rem" }}>
-            <SchemaNode
-              schema={firstBody}
-              schemaType="request"
-              schemaPath="requestBody"
-            />
-          </ul>
-        </Details>
+              <ul style={{ marginLeft: "1rem" }}>
+                <SchemaNode
+                  schema={firstBody}
+                  schemaType="request"
+                  schemaPath="requestBody"
+                />
+              </ul>
+            </Details>
+          </TabItem>
+          {firstBody &&
+            !requestExample &&
+            !requestExamples &&
+            ExampleFromSchema({
+              schema: firstBody,
+              mimeType: randomFirstKey,
+            })}
+          {requestExamples &&
+            ResponseExamples({
+              responseExamples: requestExamples,
+              mimeType: randomFirstKey,
+            })}
+          {requestExample &&
+            ResponseExample({
+              responseExample: requestExample,
+              mimeType: randomFirstKey,
+            })}
+        </SchemaTabs>
       </TabItem>
     </MimeTabs>
   );

package/src/theme/ResponseHeaders/index.tsx

@@ -9,7 +9,7 @@ import React from "react";
 
 import SchemaItem from "@theme/SchemaItem";
 
-import { getQualifierMessage, getSchemaName } from "../../markdown/schema";
+import { getSchemaName } from "../../markdown/schema";
 
 interface ResponseHeadersProps {
   description?: string;
@@ -35,7 +35,6 @@ export const ResponseHeaders: React.FC<{
             name={name}
             collapsible={false}
             schemaName={getSchemaName(schema)}
-            qualifierMessage={getQualifierMessage(schema)}
             schema={schema}
             discriminator={false}
             children={null}

package/src/theme/Schema/index.tsx

@@ -21,16 +21,11 @@ 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 {
-  getQualifierMessage,
-  getSchemaName,
-} from "docusaurus-plugin-openapi-docs/lib/markdown/schema";
-import type {
-  SchemaObject,
-  SchemaType,
-} from "docusaurus-plugin-openapi-docs/src/openapi/types";
 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");
 
@@ -41,7 +36,81 @@ const mergeAllOf = (allOf: any) => {
 
   const mergedSchemas = merge(allOf, { onMergeError });
 
-  return mergedSchemas;
+  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 {
@@ -140,6 +209,14 @@ const AnyOneOf: React.FC<SchemaProps> = ({
   schemaPath,
 }) => {
   const key = schema.oneOf ? "oneOf" : "anyOf";
+  const schemaArray = schema[key];
+
+  // Empty oneOf/anyOf arrays are valid in OpenAPI specs but would cause the
+  // Tabs component to throw "requires at least one TabItem". Return null instead.
+  if (!schemaArray || !Array.isArray(schemaArray) || schemaArray.length === 0) {
+    return null;
+  }
+
   const type = schema.oneOf
     ? translate({ id: OPENAPI_SCHEMA_ITEM.ONE_OF, message: "oneOf" })
     : translate({ id: OPENAPI_SCHEMA_ITEM.ANY_OF, message: "anyOf" });
@@ -222,7 +299,6 @@ const AnyOneOf: React.FC<SchemaProps> = ({
                   collapsible={false}
                   name={undefined}
                   schemaName={computedSchemaName}
-                  qualifierMessage={getQualifierMessage(anyOneSchema)}
                   schema={anyOneSchema}
                   discriminator={false}
                   children={null}
@@ -239,7 +315,6 @@ const AnyOneOf: React.FC<SchemaProps> = ({
                     collapsible={false}
                     name={undefined}
                     schemaName={computedSchemaName}
-                    qualifierMessage={getQualifierMessage(anyOneSchema)}
                     schema={anyOneSchema}
                     discriminator={false}
                     children={null}
@@ -313,13 +388,17 @@ const Properties: React.FC<SchemaProps> = ({
     discriminator["mapping"] = inferredMapping;
   }
   if (Object.keys(schema.properties as {}).length === 0) {
+    // Hide placeholder only for discriminator cleanup artifacts; preserve
+    // empty object rendering for schemas that intentionally define no properties.
+    if (discriminator) {
+      return null;
+    }
     return (
       <SchemaItem
         collapsible={false}
         name=""
         required={false}
         schemaName="object"
-        qualifierMessage={undefined}
         schema={{}}
       />
     );
@@ -442,10 +521,9 @@ const DiscriminatorNode: React.FC<DiscriminatorNodeProps> = ({
   let discriminatedSchemas: any = {};
   let inferredMapping: any = {};
 
-  // default to empty object if no parent-level properties exist
-  const discriminatorProperty = schema.properties
-    ? schema.properties![discriminator.propertyName]
-    : {};
+  // Search for the discriminator property in the schema, including nested structures
+  const discriminatorProperty =
+    findProperty(schema, discriminator.propertyName) ?? {};
 
   if (schema.allOf) {
     const mergedSchemas = mergeAllOf(schema) as SchemaObject;
@@ -533,7 +611,6 @@ const AdditionalProperties: React.FC<SchemaProps> = ({
         name="property name*"
         required={false}
         schemaName="any"
-        qualifierMessage={getQualifierMessage(schema)}
         schema={schema}
         collapsible={false}
         discriminator={false}
@@ -579,7 +656,6 @@ const AdditionalProperties: React.FC<SchemaProps> = ({
         name="property name*"
         required={false}
         schemaName={schemaName}
-        qualifierMessage={getQualifierMessage(schema)}
         schema={additionalProperties}
         collapsible={false}
         discriminator={false}
@@ -689,7 +765,6 @@ const Items: React.FC<{
           collapsible={false}
           name="" // No name for array items
           schemaName={getSchemaName(itemsSchema)}
-          qualifierMessage={getQualifierMessage(itemsSchema)}
           schema={itemsSchema}
           discriminator={false}
           children={null}
@@ -849,7 +924,6 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
             Array.isArray(required) ? required.includes(name) : required
           }
           schemaName={schema.allOf[0]}
-          qualifierMessage={undefined}
           schema={schema.allOf[0]}
           discriminator={false}
           children={null}
@@ -921,7 +995,6 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
         name={name}
         required={Array.isArray(required) ? required.includes(name) : required}
         schemaName={mergedSchemaName}
-        qualifierMessage={getQualifierMessage(mergedSchemas)}
         schema={mergedSchemas}
         discriminator={false}
         children={null}
@@ -935,7 +1008,6 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
       name={name}
       required={Array.isArray(required) ? required.includes(name) : required}
       schemaName={schemaName}
-      qualifierMessage={getQualifierMessage(schema)}
       schema={schema}
       discriminator={false}
       children={null}
@@ -997,12 +1069,24 @@ const SchemaNode: React.FC<SchemaProps> = ({
     return null;
   }
 
-  if (schema.discriminator) {
-    const { discriminator } = schema;
+  // Resolve discriminator recursively so nested oneOf/anyOf/allOf compositions
+  // can still render discriminator tabs.
+  let workingSchema = schema;
+  const resolvedDiscriminator =
+    schema.discriminator ?? findDiscriminator(schema);
+  if (schema.allOf && !schema.discriminator && resolvedDiscriminator) {
+    workingSchema = mergeAllOf(schema) as SchemaObject;
+  }
+  if (!workingSchema.discriminator && resolvedDiscriminator) {
+    workingSchema.discriminator = resolvedDiscriminator;
+  }
+
+  if (workingSchema.discriminator) {
+    const { discriminator } = workingSchema;
     return (
       <DiscriminatorNode
         discriminator={discriminator}
-        schema={schema}
+        schema={workingSchema}
         schemaType={schemaType}
       />
     );
@@ -1127,7 +1211,6 @@ const SchemaNode: React.FC<SchemaProps> = ({
         name={schema.type}
         required={Boolean(schema.required)}
         schemaName={schemaName}
-        qualifierMessage={getQualifierMessage(schema)}
         schema={schema}
         discriminator={false}
         children={null}
@@ -1140,7 +1223,9 @@ const SchemaNode: React.FC<SchemaProps> = ({
 
 export default SchemaNode;
 
-type PrimitiveSchemaType = Exclude<SchemaType, "object" | "array">;
+type PrimitiveSchemaType =
+  | Exclude<NonNullable<SchemaObject["type"]>, "object" | "array">
+  | "null";
 
 const PRIMITIVE_TYPES: Record<PrimitiveSchemaType, true> = {
   string: true,

package/src/theme/SchemaItem/index.tsx

@@ -13,6 +13,7 @@ import Markdown from "@theme/Markdown";
 import { OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
 import clsx from "clsx";
 
+import { getQualifierMessage } from "../../markdown/schema";
 import { guard } from "../../markdown/utils";
 
 export interface Props {
@@ -130,7 +131,11 @@ export default function SchemaItem(props: Props) {
     </>
   ));
 
-  const renderQualifierMessage = guard(qualifierMessage, (message) => (
+  // Generate qualifierMessage from schema if not provided
+  const effectiveQualifierMessage =
+    qualifierMessage ?? (schema ? getQualifierMessage(schema) : undefined);
+
+  const renderQualifierMessage = guard(effectiveQualifierMessage, (message) => (
     <>
       <Markdown>{message}</Markdown>
     </>

package/src/theme/SchemaTabs/index.tsx

@@ -16,11 +16,12 @@ import React, {
 
 import {
   sanitizeTabsChildren,
+  type TabItemProps,
   TabProps,
+  TabsProvider,
   useScrollPositionBlocker,
-  useTabs,
+  useTabsContextValue,
 } from "@docusaurus/theme-common/internal";
-import { TabItemProps } from "@docusaurus/theme-common/lib/utils/tabsUtils";
 import useIsBrowser from "@docusaurus/useIsBrowser";
 import clsx from "clsx";
 import flatten from "lodash/flatten";
@@ -40,7 +41,7 @@ function TabList({
   selectValue,
   tabValues,
   onChange,
-}: SchemaTabsProps & ReturnType<typeof useTabs>) {
+}: SchemaTabsProps & ReturnType<typeof useTabsContextValue>) {
   const tabRefs: (HTMLLIElement | null)[] = [];
   const { blockElementScrollPositionUntilNextRender } =
     useScrollPositionBlocker();
@@ -188,7 +189,7 @@ function TabContent({
   lazy,
   children,
   selectedValue,
-}: SchemaTabsProps & ReturnType<typeof useTabs>) {
+}: SchemaTabsProps & ReturnType<typeof useTabsContextValue>) {
   const childTabs = (Array.isArray(children) ? children : [children]).filter(
     Boolean
   ) as ReactElement<TabItemProps>[];
@@ -203,28 +204,48 @@ function TabContent({
     }
     return cloneElement(selectedTabItem, { className: "margin-top--md" });
   }
-  return (
-    <div className="margin-top--md">
-      {childTabs.map((tabItem, i) =>
-        cloneElement(tabItem, {
-          key: i,
-          hidden: tabItem.props.value !== selectedValue,
-        })
-      )}
-    </div>
-  );
+  return <div className="margin-top--md">{childTabs}</div>;
 }
 function TabsComponent(props: SchemaTabsProps): React.JSX.Element {
-  const tabs = useTabs(props);
+  const tabs = useTabsContextValue(props);
   return (
-    <div className="openapi-tabs__schema-container">
-      <TabList {...props} {...tabs} />
-      <TabContent {...props} {...tabs} />
-    </div>
+    <TabsProvider value={tabs}>
+      <div className="openapi-tabs__schema-container">
+        <TabList {...props} {...tabs} />
+        <TabContent {...props} {...tabs} />
+      </div>
+    </TabsProvider>
   );
 }
-export default function SchemaTabs(props: SchemaTabsProps): React.JSX.Element {
+export default function SchemaTabs(
+  props: SchemaTabsProps
+): React.JSX.Element | null {
   const isBrowser = useIsBrowser();
+
+  const children = Array.isArray(props.children)
+    ? props.children.filter(Boolean)
+    : props.children
+      ? [props.children]
+      : [];
+
+  if (children.length === 0) {
+    return null;
+  }
+
+  let sanitizedChildren;
+  try {
+    sanitizedChildren = sanitizeTabsChildren(children);
+  } catch {
+    return null;
+  }
+
+  if (
+    !sanitizedChildren ||
+    (Array.isArray(sanitizedChildren) && sanitizedChildren.length === 0)
+  ) {
+    return null;
+  }
+
   return (
     <TabsComponent
       // Remount tabs after hydration
@@ -232,7 +253,7 @@ export default function SchemaTabs(props: SchemaTabsProps): React.JSX.Element {
       key={String(isBrowser)}
       {...props}
     >
-      {sanitizeTabsChildren(props.children)}
+      {sanitizedChildren}
     </TabsComponent>
   );
 }

package/src/theme/styles.scss

@@ -9,6 +9,7 @@
 @use "./ApiExplorer/FloatingButton/FloatingButton";
 @use "./ApiExplorer/FormFileUpload/FormFileUpload";
 @use "./ApiExplorer/FormItem/FormItem";
+@use "./ApiExplorer/FormLabel/FormLabel";
 @use "./ApiExplorer/FormMultiSelect/FormMultiSelect";
 @use "./ApiExplorer/FormSelect/FormSelect";
 @use "./ApiExplorer/FormTextInput/FormTextInput";