docusaurus-theme-openapi-docs 4.5.1 → 4.7.0

package/src/theme/ApiExplorer/Body/index.tsx

@@ -5,28 +5,26 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import React from "react";
+import React, { useEffect, useMemo } from "react";
+
+import { translate } from "@docusaurus/Translate";
 
 import json2xml from "@theme/ApiExplorer/Body/json2xml";
 import FormFileUpload from "@theme/ApiExplorer/FormFileUpload";
 import FormItem from "@theme/ApiExplorer/FormItem";
-import FormSelect from "@theme/ApiExplorer/FormSelect";
-import FormTextInput from "@theme/ApiExplorer/FormTextInput";
 import LiveApp from "@theme/ApiExplorer/LiveEditor";
 import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
 import Markdown from "@theme/Markdown";
 import SchemaTabs from "@theme/SchemaTabs";
 import TabItem from "@theme/TabItem";
+import { OPENAPI_BODY, OPENAPI_REQUEST } from "@theme/translationIds";
 import { RequestBodyObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import { sampleFromSchema } from "docusaurus-plugin-openapi-docs/src/openapi/createSchemaExample";
 import format from "xml-formatter";
 
-import {
-  clearFormBodyKey,
-  clearRawBody,
-  setFileFormBody,
-  setFileRawBody,
-  setStringFormBody,
-} from "./slice";
+import { clearRawBody, setFileRawBody, setStringRawBody } from "./slice";
+import FormBodyItem from "./FormBodyItem";
+import { resolveSchemaWithSelections } from "./resolveSchemaWithSelections";
 
 export interface Props {
   jsonRequestBodyExample: string;
@@ -67,6 +65,9 @@ function Body({
   required,
 }: Props) {
   const contentType = useTypedSelector((state: any) => state.contentType.value);
+  const schemaSelections = useTypedSelector(
+    (state: any) => state.schemaSelection?.selections ?? {}
+  );
   const dispatch = useTypedDispatch();
 
   // Lot's of possible content-types:
@@ -90,15 +91,208 @@ function Body({
   // - multipart/form-data
   // - application/x-www-form-urlencoded
 
-  const schema = requestBodyMetadata?.content?.[contentType]?.schema;
+  const rawSchema = requestBodyMetadata?.content?.[contentType]?.schema;
   const example = requestBodyMetadata?.content?.[contentType]?.example;
   const examples = requestBodyMetadata?.content?.[contentType]?.examples;
 
+  // Resolve the schema based on user's anyOf/oneOf tab selections
+  const schema = useMemo(() => {
+    if (!rawSchema) return rawSchema;
+    return resolveSchemaWithSelections(
+      rawSchema,
+      schemaSelections,
+      "requestBody"
+    );
+  }, [rawSchema, schemaSelections]);
+
+  // OpenAPI 3.1 / JSON Schema: schema.examples is an array of example values
+  const schemaExamples = schema?.examples as any[] | undefined;
+
+  // Compute the default body based on content type and schema
+  // This needs to be computed before early returns so the useEffect can use it
+  const { defaultBody, exampleBody, examplesBodies, language } = useMemo(() => {
+    let lang = "plaintext";
+    let defBody = "";
+    let exBody;
+    let exBodies = [] as any;
+
+    // Skip body generation for binary and form content types
+    if (schema?.format === "binary") {
+      return {
+        defaultBody: defBody,
+        exampleBody: exBody,
+        examplesBodies: exBodies,
+        language: lang,
+      };
+    }
+    if (
+      (contentType === "multipart/form-data" ||
+        contentType === "application/x-www-form-urlencoded") &&
+      schema?.type === "object"
+    ) {
+      return {
+        defaultBody: defBody,
+        exampleBody: exBody,
+        examplesBodies: exBodies,
+        language: lang,
+      };
+    }
+
+    // Generate example from the schema for the current content type
+    let contentTypeExample;
+    if (schema) {
+      contentTypeExample = sampleFromSchema(schema, { type: "request" });
+    } else if (jsonRequestBodyExample) {
+      // Fallback to the build-time generated example if no schema is available
+      contentTypeExample = jsonRequestBodyExample;
+    }
+
+    if (
+      contentType?.includes("application/json") ||
+      contentType?.endsWith("+json")
+    ) {
+      if (contentTypeExample) {
+        defBody = JSON.stringify(contentTypeExample, null, 2);
+      }
+      if (example) {
+        exBody = JSON.stringify(example, null, 2);
+      }
+      if (examples) {
+        for (const [key, ex] of Object.entries(examples)) {
+          let body = ex.value;
+          try {
+            // If the value is already valid JSON we shouldn't double encode the value
+            JSON.parse(ex.value);
+          } catch (e) {
+            body = JSON.stringify(ex.value, null, 2);
+          }
+
+          exBodies.push({
+            label: key,
+            body,
+            summary: ex.summary,
+          });
+        }
+      }
+      // OpenAPI 3.1: schema.examples is an array of example values
+      if (schemaExamples && Array.isArray(schemaExamples)) {
+        schemaExamples.forEach((schemaExample, index) => {
+          const body = JSON.stringify(schemaExample, null, 2);
+          exBodies.push({
+            label: `Example ${index + 1}`,
+            body,
+            summary: undefined,
+          });
+        });
+      }
+      lang = "json";
+    }
+
+    if (contentType === "application/xml" || contentType?.endsWith("+xml")) {
+      if (contentTypeExample) {
+        try {
+          defBody = format(json2xml(contentTypeExample, ""), {
+            indentation: "  ",
+            lineSeparator: "\n",
+            collapseContent: true,
+          });
+        } catch {
+          defBody = json2xml(contentTypeExample);
+        }
+      }
+      if (example) {
+        try {
+          exBody = format(json2xml(example, ""), {
+            indentation: "  ",
+            lineSeparator: "\n",
+            collapseContent: true,
+          });
+        } catch {
+          exBody = json2xml(example);
+        }
+      }
+      if (examples) {
+        for (const [key, ex] of Object.entries(examples)) {
+          let formattedXmlBody;
+          try {
+            formattedXmlBody = format(ex.value, {
+              indentation: "  ",
+              lineSeparator: "\n",
+              collapseContent: true,
+            });
+          } catch {
+            formattedXmlBody = ex.value;
+          }
+          exBodies.push({
+            label: key,
+            body: formattedXmlBody,
+            summary: ex.summary,
+          });
+        }
+      }
+      // OpenAPI 3.1: schema.examples is an array of example values
+      if (schemaExamples && Array.isArray(schemaExamples)) {
+        schemaExamples.forEach((schemaExample, index) => {
+          let formattedXmlBody;
+          try {
+            formattedXmlBody = format(json2xml(schemaExample, ""), {
+              indentation: "  ",
+              lineSeparator: "\n",
+              collapseContent: true,
+            });
+          } catch {
+            formattedXmlBody = json2xml(schemaExample);
+          }
+          exBodies.push({
+            label: `Example ${index + 1}`,
+            body: formattedXmlBody,
+            summary: undefined,
+          });
+        });
+      }
+      lang = "xml";
+    }
+
+    return {
+      defaultBody: defBody,
+      exampleBody: exBody,
+      examplesBodies: exBodies,
+      language: lang,
+    };
+  }, [
+    schema,
+    contentType,
+    example,
+    examples,
+    schemaExamples,
+    jsonRequestBodyExample,
+  ]);
+
+  // Create a stable key for the LiveApp component that changes when schema selection changes
+  // This forces the editor to remount and pick up the new defaultBody
+  const schemaSelectionKey = useMemo(
+    () => JSON.stringify(schemaSelections),
+    [schemaSelections]
+  );
+
+  // Update body in Redux when content type or schema selection changes
+  useEffect(() => {
+    if (defaultBody) {
+      dispatch(setStringRawBody(defaultBody));
+    }
+    // Re-run when contentType, schemaSelections, or defaultBody change
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [contentType, schemaSelections, defaultBody]);
+
+  // Now handle early returns after all hooks have been called
   if (schema?.format === "binary") {
     return (
       <FormItem>
         <FormFileUpload
-          placeholder={schema.description || "Body"}
+          placeholder={
+            schema.description ||
+            translate({ id: OPENAPI_REQUEST.BODY_TITLE, message: "Body" })
+          }
           onChange={(file: any) => {
             if (file === undefined) {
               dispatch(clearRawBody());
@@ -115,6 +309,7 @@ function Body({
       </FormItem>
     );
   }
+
   if (
     (contentType === "multipart/form-data" ||
       contentType === "application/x-www-form-urlencoded") &&
@@ -122,191 +317,46 @@ function Body({
   ) {
     return (
       <FormItem className="openapi-explorer__form-item-body-container">
-        <div>
-          {Object.entries(schema.properties ?? {}).map(([key, val]: any) => {
-            if (val.format === "binary") {
-              return (
-                <FormItem
-                  key={key}
-                  label={key}
-                  required={
-                    Array.isArray(schema.required) &&
-                    schema.required.includes(key)
-                  }
-                >
-                  <FormFileUpload
-                    placeholder={val.description || key}
-                    onChange={(file: any) => {
-                      if (file === undefined) {
-                        dispatch(clearFormBodyKey(key));
-                        return;
-                      }
-                      dispatch(
-                        setFileFormBody({
-                          key: key,
-                          value: {
-                            src: `/path/to/${file.name}`,
-                            content: file,
-                          },
-                        })
-                      );
-                    }}
-                  />
-                </FormItem>
-              );
-            }
-
-            if (val.enum) {
-              return (
-                <FormItem
-                  key={key}
-                  label={key}
-                  required={
-                    Array.isArray(schema.required) &&
-                    schema.required.includes(key)
-                  }
-                >
-                  <FormSelect
-                    options={["---", ...val.enum]}
-                    onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
-                      const val = e.target.value;
-                      if (val === "---") {
-                        dispatch(clearFormBodyKey(key));
-                      } else {
-                        dispatch(
-                          setStringFormBody({
-                            key: key,
-                            value: val,
-                          })
-                        );
-                      }
-                    }}
-                  />
-                </FormItem>
-              );
-            }
-            // TODO: support all the other types.
-            return (
-              <FormItem
-                key={key}
-                label={key}
-                required={
-                  Array.isArray(schema.required) &&
-                  schema.required.includes(key)
-                }
-              >
-                <FormTextInput
-                  paramName={key}
-                  isRequired={
-                    Array.isArray(schema.required) &&
-                    schema.required.includes(key)
-                  }
-                  placeholder={val.description || key}
-                  onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
-                    dispatch(
-                      setStringFormBody({ key: key, value: e.target.value })
-                    );
-                  }}
-                />
-              </FormItem>
-            );
-          })}
-        </div>
+        {Object.entries(schema.properties ?? {}).map(([key, val]: any) => {
+          return (
+            <FormItem
+              key={key}
+              label={key}
+              required={
+                Array.isArray(schema.required) && schema.required.includes(key)
+              }
+            >
+              <FormBodyItem
+                schemaObject={val}
+                id={key}
+                schema={schema}
+              ></FormBodyItem>
+            </FormItem>
+          );
+        })}
       </FormItem>
     );
   }
 
-  let language = "plaintext";
-  let defaultBody = ""; //"body content";
-  let exampleBody;
-  let examplesBodies = [] as any;
-
-  if (
-    contentType.includes("application/json") ||
-    contentType.endsWith("+json")
-  ) {
-    if (jsonRequestBodyExample) {
-      defaultBody = JSON.stringify(jsonRequestBodyExample, null, 2);
-    }
-    if (example) {
-      exampleBody = JSON.stringify(example, null, 2);
-    }
-    if (examples) {
-      for (const [key, example] of Object.entries(examples)) {
-        let body = example.value;
-        try {
-          // If the value is already valid JSON we shouldn't double encode the value
-          JSON.parse(example.value);
-        } catch (e) {
-          body = JSON.stringify(example.value, null, 2);
-        }
-
-        examplesBodies.push({
-          label: key,
-          body,
-          summary: example.summary,
-        });
-      }
-    }
-    language = "json";
-  }
-
-  if (contentType === "application/xml" || contentType.endsWith("+xml")) {
-    if (jsonRequestBodyExample) {
-      try {
-        defaultBody = format(json2xml(jsonRequestBodyExample, ""), {
-          indentation: "  ",
-          lineSeparator: "\n",
-          collapseContent: true,
-        });
-      } catch {
-        defaultBody = json2xml(jsonRequestBodyExample);
-      }
-    }
-    if (example) {
-      try {
-        exampleBody = format(json2xml(example, ""), {
-          indentation: "  ",
-          lineSeparator: "\n",
-          collapseContent: true,
-        });
-      } catch {
-        exampleBody = json2xml(example);
-      }
-    }
-    if (examples) {
-      for (const [key, example] of Object.entries(examples)) {
-        let formattedXmlBody;
-        try {
-          formattedXmlBody = format(example.value, {
-            indentation: "  ",
-            lineSeparator: "\n",
-            collapseContent: true,
-          });
-        } catch {
-          formattedXmlBody = example.value;
-        }
-        examplesBodies.push({
-          label: key,
-          body: formattedXmlBody,
-          summary: example.summary,
-        });
-      }
-    }
-    language = "xml";
-  }
-
   if (exampleBody) {
     return (
       <FormItem>
         <SchemaTabs className="openapi-tabs__schema" lazy>
           {/* @ts-ignore */}
           <TabItem
-            label="Example (from schema)"
+            label={translate({
+              id: OPENAPI_BODY.EXAMPLE_FROM_SCHEMA,
+              message: "Example (from schema)",
+            })}
             value="Example (from schema)"
             default
           >
-            <LiveApp action={dispatch} language={language} required={required}>
+            <LiveApp
+              key={`${contentType}-${schemaSelectionKey}`}
+              action={(code: string) => dispatch(setStringRawBody(code))}
+              language={language}
+              required={required}
+            >
               {defaultBody}
             </LiveApp>
           </TabItem>
@@ -315,7 +365,8 @@ function Body({
             {example.summary && <Markdown>{example.summary}</Markdown>}
             {exampleBody && (
               <LiveApp
-                action={dispatch}
+                key={`${contentType}-example`}
+                action={(code: string) => dispatch(setStringRawBody(code))}
                 language={language}
                 required={required}
               >
@@ -334,26 +385,34 @@ function Body({
         <SchemaTabs className="openapi-tabs__schema" lazy>
           {/* @ts-ignore */}
           <TabItem
-            label="Example (from schema)"
+            label={translate({
+              id: OPENAPI_BODY.EXAMPLE_FROM_SCHEMA,
+              message: "Example (from schema)",
+            })}
             value="Example (from schema)"
             default
           >
-            <LiveApp action={dispatch} language={language} required={required}>
+            <LiveApp
+              key={`${contentType}-${schemaSelectionKey}`}
+              action={(code: string) => dispatch(setStringRawBody(code))}
+              language={language}
+              required={required}
+            >
               {defaultBody}
             </LiveApp>
           </TabItem>
-          {examplesBodies.map((example: any) => {
+          {examplesBodies.map((ex: any) => {
             return (
               // @ts-ignore
-              <TabItem
-                label={example.label}
-                value={example.label}
-                key={example.label}
-              >
-                {example.summary && <Markdown>{example.summary}</Markdown>}
-                {example.body && (
-                  <LiveApp action={dispatch} language={language}>
-                    {example.body}
+              <TabItem label={ex.label} value={ex.label} key={ex.label}>
+                {ex.summary && <Markdown>{ex.summary}</Markdown>}
+                {ex.body && (
+                  <LiveApp
+                    key={`${contentType}-${ex.label}`}
+                    action={(code: string) => dispatch(setStringRawBody(code))}
+                    language={language}
+                  >
+                    {ex.body}
                   </LiveApp>
                 )}
               </TabItem>
@@ -366,7 +425,12 @@ function Body({
 
   return (
     <FormItem>
-      <LiveApp action={dispatch} language={language} required={required}>
+      <LiveApp
+        key={`${contentType}-${schemaSelectionKey}`}
+        action={(code: string) => dispatch(setStringRawBody(code))}
+        language={language}
+        required={required}
+      >
         {defaultBody}
       </LiveApp>
     </FormItem>

package/{lib/types.js → src/theme/ApiExplorer/Body/json2xml.d.ts}

@@ -1,8 +1,8 @@
-"use strict";
 /* ============================================================================
  * Copyright (c) Palo Alto Networks
  *
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
-Object.defineProperty(exports, "__esModule", { value: true });
+
+export default function json2xml(input: any, indent?: any): any;