add exmaples for schema property

Author: dsuket

packages/docusaurus-theme-openapi-docs/src/theme/ParamsItem/index.tsx

@@ -21,18 +21,18 @@ interface Map<T> {
 }
 
 export interface ExampleObject {
-  summary?: string;
-  description?: string;
+  summary?: string | null;
+  description?: string | null;
   value?: any;
-  externalValue?: string;
+  externalValue?: string | null;
 }
 
 export interface Props {
   className: string;
   param: {
     description: string;
     example: any;
-    examples: Map<ExampleObject>;
+    examples: Map<ExampleObject> | any[];
     name: string;
     required: boolean;
     deprecated: boolean;
@@ -57,19 +57,14 @@ ${enumDescriptions
 };
 
 function ParamsItem({ param, ...rest }: Props) {
-  const {
-    description,
-    example,
-    examples,
-    name,
-    required,
-    deprecated,
-    enumDescriptions,
-  } = param;
+  const { description, name, required, deprecated, enumDescriptions } = param;
 
   let schema = param.schema;
   let defaultValue: string | undefined;
 
+  let examples = param.examples || schema?.examples;
+  let example = param.example || schema?.example;
+
   if (!schema) {
     schema = { type: "any" };
   }
@@ -144,32 +139,75 @@ function ParamsItem({ param, ...rest }: Props) {
   const renderExample = guard(toString(example), (example) => (
     <div>
       <strong>Example: </strong>
-      {example}
+      <code>{example}</code>
     </div>
   ));
 
+  // Helper function to format example value
+  const formatExample = (example: any) => {
+    if (typeof example === "object" && example !== null) {
+      return JSON.stringify(example);
+    }
+    return String(example);
+  };
+
+  const renderExampleTabItem = (
+    exampleName: string,
+    exampleProperties: ExampleObject
+  ) => {
+    return (
+      // @ts-ignore
+      <TabItem value={exampleName} label={exampleName}>
+        {exampleProperties.summary && <p>{exampleProperties.summary}</p>}
+        {exampleProperties.description && (
+          <p>
+            <strong>Description: </strong>
+            <span>{exampleProperties.description}</span>
+          </p>
+        )}
+        <p>
+          <strong>Example: </strong>
+          <code>{formatExample(exampleProperties.value)}</code>
+        </p>
+      </TabItem>
+    );
+  };
+
   const renderExamples = guard(examples, (examples) => {
-    const exampleEntries = Object.entries(examples);
+    // Handle object-based examples (existing logic)
+    let exampleEntries: [string, ExampleObject][];
+    if (Array.isArray(examples)) {
+      exampleEntries = examples.map((example, index) => [
+        `Example ${index + 1}`,
+        { value: example, summary: null, description: null },
+      ]);
+    } else {
+      exampleEntries = Object.entries(examples);
+    }
+
+    // If there's only one example, display it without tabs
+    if (exampleEntries.length === 1) {
+      const firstExample = exampleEntries[0][1];
+      if (!firstExample) {
+        return undefined;
+      }
+      return (
+        <div>
+          <strong>Example: </strong>
+          <span>
+            <code>{formatExample(firstExample.value)}</code>
+          </span>
+        </div>
+      );
+    }
+
     return (
       <>
         <strong>Examples:</strong>
         <SchemaTabs>
-          {exampleEntries.map(([exampleName, exampleProperties]) => (
-            // @ts-ignore
-            <TabItem value={exampleName} label={exampleName}>
-              {exampleProperties.summary && <p>{exampleProperties.summary}</p>}
-              {exampleProperties.description && (
-                <p>
-                  <strong>Description: </strong>
-                  <span>{exampleProperties.description}</span>
-                </p>
-              )}
-              <p>
-                <strong>Example: </strong>
-                <code>{exampleProperties.value}</code>
-              </p>
-            </TabItem>
-          ))}
+          {exampleEntries.map(([exampleName, exampleProperties]) =>
+            renderExampleTabItem(exampleName, exampleProperties)
+          )}
         </SchemaTabs>
       </>
     );

packages/docusaurus-theme-openapi-docs/src/theme/SchemaItem/index.tsx

@@ -8,6 +8,8 @@
 import React, { ReactNode } from "react";
 
 import Markdown from "@theme/Markdown";
+import SchemaTabs from "@theme/SchemaTabs";
+import TabItem from "@theme/TabItem";
 import clsx from "clsx";
 
 import { guard } from "../../markdown/utils";
@@ -63,6 +65,7 @@ export default function SchemaItem(props: Props) {
   let schemaDescription;
   let defaultValue: string | undefined;
   let example: string | undefined;
+  let examples: string[] | undefined;
   let nullable;
   let enumDescriptions: [string, string][] = [];
   let constValue: string | undefined;
@@ -73,6 +76,7 @@ export default function SchemaItem(props: Props) {
     enumDescriptions = transformEnumDescriptions(schema["x-enumDescriptions"]);
     defaultValue = schema.default;
     example = schema.example;
+    examples = schema.examples;
     nullable =
       schema.nullable ||
       (Array.isArray(schema.type) && schema.type.includes("null")); // support JSON Schema nullable
@@ -163,6 +167,53 @@ export default function SchemaItem(props: Props) {
     return undefined;
   }
 
+  // Helper function to format example value
+  const formatExample = (example: any) => {
+    if (typeof example === "object" && example !== null) {
+      return JSON.stringify(example);
+    }
+    return String(example);
+  };
+
+  function renderExamples() {
+    if (examples && examples.length > 0) {
+      // If there's only one example, display it without tabs
+      if (examples.length === 1) {
+        return (
+          <div>
+            <strong>Example: </strong>
+            <span>
+              <code>{formatExample(examples[0])}</code>
+            </span>
+          </div>
+        );
+      }
+
+      // Multiple examples - use tabs
+      return (
+        <div>
+          <strong>Examples:</strong>
+          <SchemaTabs>
+            {examples.map((example, index) => (
+              // @ts-ignore
+              <TabItem
+                value={`Example ${index + 1}`}
+                label={`Example ${index + 1}`}
+                key={`Example ${index + 1}`}
+              >
+                <p>
+                  <strong>Example: </strong>
+                  <code>{formatExample(example)}</code>
+                </p>
+              </TabItem>
+            ))}
+          </SchemaTabs>
+        </div>
+      );
+    }
+    return undefined;
+  }
+
   function renderConstValue() {
     if (constValue !== undefined) {
       if (typeof constValue === "string") {
@@ -213,6 +264,7 @@ export default function SchemaItem(props: Props) {
       {renderConstValue()}
       {renderDefaultValue()}
       {renderExample()}
+      {renderExamples()}
       {collapsibleSchemaContent ?? collapsibleSchemaContent}
     </div>
   );