docusaurus-theme-openapi-docs 4.6.0 → 4.7.0

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

@@ -5,7 +5,7 @@
  * 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";
 
@@ -19,10 +19,12 @@ 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 { clearRawBody, setFileRawBody, setStringRawBody } from "./slice";
 import FormBodyItem from "./FormBodyItem";
+import { resolveSchemaWithSelections } from "./resolveSchemaWithSelections";
 
 export interface Props {
   jsonRequestBodyExample: string;
@@ -63,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:
@@ -86,12 +91,200 @@ 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>
@@ -116,6 +309,7 @@ function Body({
       </FormItem>
     );
   }
+
   if (
     (contentType === "multipart/form-data" ||
       contentType === "application/x-www-form-urlencoded") &&
@@ -144,117 +338,6 @@ function Body({
     );
   }
 
-  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,
-        });
-      }
-    }
-    // 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);
-        examplesBodies.push({
-          label: `Example ${index + 1}`,
-          body,
-          summary: undefined,
-        });
-      });
-    }
-    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,
-        });
-      }
-    }
-    // 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);
-        }
-        examplesBodies.push({
-          label: `Example ${index + 1}`,
-          body: formattedXmlBody,
-          summary: undefined,
-        });
-      });
-    }
-    language = "xml";
-  }
-
   if (exampleBody) {
     return (
       <FormItem>
@@ -269,6 +352,7 @@ function Body({
             default
           >
             <LiveApp
+              key={`${contentType}-${schemaSelectionKey}`}
               action={(code: string) => dispatch(setStringRawBody(code))}
               language={language}
               required={required}
@@ -281,6 +365,7 @@ function Body({
             {example.summary && <Markdown>{example.summary}</Markdown>}
             {exampleBody && (
               <LiveApp
+                key={`${contentType}-example`}
                 action={(code: string) => dispatch(setStringRawBody(code))}
                 language={language}
                 required={required}
@@ -308,6 +393,7 @@ function Body({
             default
           >
             <LiveApp
+              key={`${contentType}-${schemaSelectionKey}`}
               action={(code: string) => dispatch(setStringRawBody(code))}
               language={language}
               required={required}
@@ -315,21 +401,18 @@ function Body({
               {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 && (
+              <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}
                   >
-                    {example.body}
+                    {ex.body}
                   </LiveApp>
                 )}
               </TabItem>
@@ -343,6 +426,7 @@ function Body({
   return (
     <FormItem>
       <LiveApp
+        key={`${contentType}-${schemaSelectionKey}`}
         action={(code: string) => dispatch(setStringRawBody(code))}
         language={language}
         required={required}

package/src/theme/ApiExplorer/Body/resolveSchemaWithSelections.ts

@@ -0,0 +1,155 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+import { SchemaObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import merge from "lodash/merge";
+
+export interface SchemaSelections {
+  [schemaPath: string]: number;
+}
+
+/**
+ * Resolves a schema by replacing anyOf/oneOf with the selected option based on user selections.
+ *
+ * @param schema - The original schema object
+ * @param selections - Map of schema paths to selected indices
+ * @param basePath - The base path for this schema (used for looking up selections)
+ * @returns A new schema with anyOf/oneOf resolved to selected options
+ */
+export function resolveSchemaWithSelections(
+  schema: SchemaObject | undefined,
+  selections: SchemaSelections,
+  basePath: string = "requestBody"
+): SchemaObject | undefined {
+  if (!schema) {
+    return schema;
+  }
+
+  // Deep clone to avoid mutating the original schema
+  const schemaCopy = JSON.parse(JSON.stringify(schema)) as SchemaObject;
+
+  return resolveSchemaRecursive(schemaCopy, selections, basePath);
+}
+
+function resolveSchemaRecursive(
+  schema: SchemaObject,
+  selections: SchemaSelections,
+  currentPath: string
+): SchemaObject {
+  // Handle oneOf
+  if (schema.oneOf && Array.isArray(schema.oneOf)) {
+    const selectedIndex = selections[currentPath] ?? 0;
+    const selectedSchema = schema.oneOf[selectedIndex] as SchemaObject;
+
+    if (selectedSchema) {
+      // If there are shared properties, merge them with the selected schema
+      if (schema.properties) {
+        const mergedSchema = merge({}, schema, selectedSchema);
+        delete mergedSchema.oneOf;
+
+        // Continue resolving nested schemas in the merged result
+        return resolveSchemaRecursive(
+          mergedSchema,
+          selections,
+          `${currentPath}.${selectedIndex}`
+        );
+      }
+
+      // No shared properties, just use the selected schema
+      // Continue resolving in case there are nested anyOf/oneOf
+      return resolveSchemaRecursive(
+        selectedSchema,
+        selections,
+        `${currentPath}.${selectedIndex}`
+      );
+    }
+  }
+
+  // Handle anyOf
+  if (schema.anyOf && Array.isArray(schema.anyOf)) {
+    const selectedIndex = selections[currentPath] ?? 0;
+    const selectedSchema = schema.anyOf[selectedIndex] as SchemaObject;
+
+    if (selectedSchema) {
+      // If there are shared properties, merge them with the selected schema
+      if (schema.properties) {
+        const mergedSchema = merge({}, schema, selectedSchema);
+        delete mergedSchema.anyOf;
+
+        // Continue resolving nested schemas in the merged result
+        return resolveSchemaRecursive(
+          mergedSchema,
+          selections,
+          `${currentPath}.${selectedIndex}`
+        );
+      }
+
+      // No shared properties, just use the selected schema
+      // Continue resolving in case there are nested anyOf/oneOf
+      return resolveSchemaRecursive(
+        selectedSchema,
+        selections,
+        `${currentPath}.${selectedIndex}`
+      );
+    }
+  }
+
+  // Handle allOf - merge all schemas and continue resolving
+  if (schema.allOf && Array.isArray(schema.allOf)) {
+    // Process each allOf item, resolving any anyOf/oneOf within them
+    const resolvedItems = schema.allOf.map((item, index) => {
+      return resolveSchemaRecursive(
+        item as SchemaObject,
+        selections,
+        `${currentPath}.allOf.${index}`
+      );
+    });
+
+    // Merge all resolved items
+    const mergedSchema = resolvedItems.reduce(
+      (acc, item) => merge(acc, item),
+      {} as SchemaObject
+    );
+
+    // Preserve any top-level properties from the original schema
+    if (schema.properties) {
+      mergedSchema.properties = merge(
+        {},
+        mergedSchema.properties,
+        schema.properties
+      );
+    }
+
+    return mergedSchema;
+  }
+
+  // Handle object properties recursively
+  if (schema.properties) {
+    const resolvedProperties: { [key: string]: SchemaObject } = {};
+
+    for (const [propName, propSchema] of Object.entries(schema.properties)) {
+      resolvedProperties[propName] = resolveSchemaRecursive(
+        propSchema as SchemaObject,
+        selections,
+        `${currentPath}.${propName}`
+      );
+    }
+
+    schema.properties = resolvedProperties;
+  }
+
+  // Handle array items recursively
+  if (schema.items) {
+    schema.items = resolveSchemaRecursive(
+      schema.items as SchemaObject,
+      selections,
+      `${currentPath}.items`
+    );
+  }
+
+  return schema;
+}

package/{lib/types.js → src/theme/ApiExplorer/SchemaSelection/index.ts}

@@ -1,8 +1,13 @@
-"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 as schemaSelectionReducer,
+  setSchemaSelection,
+  clearSchemaSelections,
+} from "./slice";
+export type { SchemaSelectionState } from "./slice";

package/src/theme/ApiExplorer/SchemaSelection/slice.ts

@@ -0,0 +1,46 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+import { createSlice, PayloadAction } from "@reduxjs/toolkit";
+
+export interface SchemaSelectionState {
+  /**
+   * Maps schema path (e.g., "requestBody", "requestBody.anyOf.0.layer3")
+   * to the selected anyOf/oneOf option index
+   */
+  selections: { [schemaPath: string]: number };
+}
+
+const initialState: SchemaSelectionState = {
+  selections: {},
+};
+
+export const slice = createSlice({
+  name: "schemaSelection",
+  initialState,
+  reducers: {
+    /**
+     * Set the selected index for a specific schema path
+     */
+    setSchemaSelection: (
+      state,
+      action: PayloadAction<{ path: string; index: number }>
+    ) => {
+      state.selections[action.payload.path] = action.payload.index;
+    },
+    /**
+     * Clear all schema selections (useful when navigating to a new API endpoint)
+     */
+    clearSchemaSelections: (state) => {
+      state.selections = {};
+    },
+  },
+});
+
+export const { setSchemaSelection, clearSchemaSelections } = slice.actions;
+
+export default slice.reducer;

package/src/theme/ApiItem/index.tsx

@@ -158,6 +158,7 @@ export default function ApiItem(props: Props): JSX.Element {
         body: { type: "empty" },
         params,
         auth,
+        schemaSelection: { selections: {} },
       },
       [persistenceMiddleware]
     );

package/src/theme/ApiItem/store.ts

@@ -12,6 +12,7 @@ import body from "@theme/ApiExplorer/Body/slice";
 import contentType from "@theme/ApiExplorer/ContentType/slice";
 import params from "@theme/ApiExplorer/ParamOptions/slice";
 import response from "@theme/ApiExplorer/Response/slice";
+import schemaSelection from "@theme/ApiExplorer/SchemaSelection/slice";
 import server from "@theme/ApiExplorer/Server/slice";
 
 const rootReducer = combineReducers({
@@ -22,6 +23,7 @@ const rootReducer = combineReducers({
   body,
   params,
   auth,
+  schemaSelection,
 });
 
 export type RootState = ReturnType<typeof rootReducer>;