docusaurus-theme-openapi-docs 4.6.0 → 4.7.0

package/lib/markdown/schema.js

@@ -11,6 +11,11 @@ exports.getQualifierMessage = getQualifierMessage;
 const Translate_1 = require("@docusaurus/Translate");
 const translationIds_1 = require("../theme/translationIds");
 function prettyName(schema, circular) {
+    // Handle enum-only schemas (valid in JSON Schema)
+    // When enum is present without explicit type, treat as string
+    if (schema.enum && !schema.type) {
+        return "string";
+    }
     if (schema.format) {
         return schema.format;
     }

package/lib/theme/ApiExplorer/Body/index.js

@@ -5,13 +5,69 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
+var __createBinding =
+  (this && this.__createBinding) ||
+  (Object.create
+    ? function (o, m, k, k2) {
+        if (k2 === undefined) k2 = k;
+        var desc = Object.getOwnPropertyDescriptor(m, k);
+        if (
+          !desc ||
+          ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)
+        ) {
+          desc = {
+            enumerable: true,
+            get: function () {
+              return m[k];
+            },
+          };
+        }
+        Object.defineProperty(o, k2, desc);
+      }
+    : function (o, m, k, k2) {
+        if (k2 === undefined) k2 = k;
+        o[k2] = m[k];
+      });
+var __setModuleDefault =
+  (this && this.__setModuleDefault) ||
+  (Object.create
+    ? function (o, v) {
+        Object.defineProperty(o, "default", { enumerable: true, value: v });
+      }
+    : function (o, v) {
+        o["default"] = v;
+      });
+var __importStar =
+  (this && this.__importStar) ||
+  (function () {
+    var ownKeys = function (o) {
+      ownKeys =
+        Object.getOwnPropertyNames ||
+        function (o) {
+          var ar = [];
+          for (var k in o)
+            if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+          return ar;
+        };
+      return ownKeys(o);
+    };
+    return function (mod) {
+      if (mod && mod.__esModule) return mod;
+      var result = {};
+      if (mod != null)
+        for (var k = ownKeys(mod), i = 0; i < k.length; i++)
+          if (k[i] !== "default") __createBinding(result, mod, k[i]);
+      __setModuleDefault(result, mod);
+      return result;
+    };
+  })();
 var __importDefault =
   (this && this.__importDefault) ||
   function (mod) {
     return mod && mod.__esModule ? mod : { default: mod };
   };
 Object.defineProperty(exports, "__esModule", { value: true });
-const react_1 = __importDefault(require("react"));
+const react_1 = __importStar(require("react"));
 const Translate_1 = require("@docusaurus/Translate");
 const json2xml_1 = __importDefault(require("@theme/ApiExplorer/Body/json2xml"));
 const FormFileUpload_1 = __importDefault(
@@ -24,9 +80,11 @@ const Markdown_1 = __importDefault(require("@theme/Markdown"));
 const SchemaTabs_1 = __importDefault(require("@theme/SchemaTabs"));
 const TabItem_1 = __importDefault(require("@theme/TabItem"));
 const translationIds_1 = require("@theme/translationIds");
+const createSchemaExample_1 = require("docusaurus-plugin-openapi-docs/src/openapi/createSchemaExample");
 const xml_formatter_1 = __importDefault(require("xml-formatter"));
 const slice_1 = require("./slice");
 const FormBodyItem_1 = __importDefault(require("./FormBodyItem"));
+const resolveSchemaWithSelections_1 = require("./resolveSchemaWithSelections");
 function BodyWrap({
   requestBodyMetadata,
   jsonRequestBodyExample,
@@ -57,6 +115,9 @@ function Body({
   const contentType = (0, hooks_1.useTypedSelector)(
     (state) => state.contentType.value
   );
+  const schemaSelections = (0, hooks_1.useTypedSelector)(
+    (state) => state.schemaSelection?.selections ?? {}
+  );
   const dispatch = (0, hooks_1.useTypedDispatch)();
   // Lot's of possible content-types:
   // - application/json
@@ -76,11 +137,200 @@ function Body({
   // Show form:
   // - 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 = (0, react_1.useMemo)(() => {
+    if (!rawSchema) return rawSchema;
+    return (0, resolveSchemaWithSelections_1.resolveSchemaWithSelections)(
+      rawSchema,
+      schemaSelections,
+      "requestBody"
+    );
+  }, [rawSchema, schemaSelections]);
   // OpenAPI 3.1 / JSON Schema: schema.examples is an array of example values
   const schemaExamples = schema?.examples;
+  // 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 } = (0,
+  react_1.useMemo)(() => {
+    let lang = "plaintext";
+    let defBody = "";
+    let exBody;
+    let exBodies = [];
+    // 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 = (0, createSchemaExample_1.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 = (0, xml_formatter_1.default)(
+            (0, json2xml_1.default)(contentTypeExample, ""),
+            {
+              indentation: "  ",
+              lineSeparator: "\n",
+              collapseContent: true,
+            }
+          );
+        } catch {
+          defBody = (0, json2xml_1.default)(contentTypeExample);
+        }
+      }
+      if (example) {
+        try {
+          exBody = (0, xml_formatter_1.default)(
+            (0, json2xml_1.default)(example, ""),
+            {
+              indentation: "  ",
+              lineSeparator: "\n",
+              collapseContent: true,
+            }
+          );
+        } catch {
+          exBody = (0, json2xml_1.default)(example);
+        }
+      }
+      if (examples) {
+        for (const [key, ex] of Object.entries(examples)) {
+          let formattedXmlBody;
+          try {
+            formattedXmlBody = (0, xml_formatter_1.default)(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 = (0, xml_formatter_1.default)(
+              (0, json2xml_1.default)(schemaExample, ""),
+              {
+                indentation: "  ",
+                lineSeparator: "\n",
+                collapseContent: true,
+              }
+            );
+          } catch {
+            formattedXmlBody = (0, json2xml_1.default)(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 = (0, react_1.useMemo)(
+    () => JSON.stringify(schemaSelections),
+    [schemaSelections]
+  );
+  // Update body in Redux when content type or schema selection changes
+  (0, react_1.useEffect)(() => {
+    if (defaultBody) {
+      dispatch((0, slice_1.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 react_1.default.createElement(
       FormItem_1.default,
@@ -133,122 +383,6 @@ function Body({
       })
     );
   }
-  let language = "plaintext";
-  let defaultBody = ""; //"body content";
-  let exampleBody;
-  let examplesBodies = [];
-  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 = (0, xml_formatter_1.default)(
-          (0, json2xml_1.default)(jsonRequestBodyExample, ""),
-          {
-            indentation: "  ",
-            lineSeparator: "\n",
-            collapseContent: true,
-          }
-        );
-      } catch {
-        defaultBody = (0, json2xml_1.default)(jsonRequestBodyExample);
-      }
-    }
-    if (example) {
-      try {
-        exampleBody = (0, xml_formatter_1.default)(
-          (0, json2xml_1.default)(example, ""),
-          {
-            indentation: "  ",
-            lineSeparator: "\n",
-            collapseContent: true,
-          }
-        );
-      } catch {
-        exampleBody = (0, json2xml_1.default)(example);
-      }
-    }
-    if (examples) {
-      for (const [key, example] of Object.entries(examples)) {
-        let formattedXmlBody;
-        try {
-          formattedXmlBody = (0, xml_formatter_1.default)(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 = (0, xml_formatter_1.default)(
-            (0, json2xml_1.default)(schemaExample, ""),
-            {
-              indentation: "  ",
-              lineSeparator: "\n",
-              collapseContent: true,
-            }
-          );
-        } catch {
-          formattedXmlBody = (0, json2xml_1.default)(schemaExample);
-        }
-        examplesBodies.push({
-          label: `Example ${index + 1}`,
-          body: formattedXmlBody,
-          summary: undefined,
-        });
-      });
-    }
-    language = "xml";
-  }
   if (exampleBody) {
     return react_1.default.createElement(
       FormItem_1.default,
@@ -269,6 +403,7 @@ function Body({
           react_1.default.createElement(
             LiveEditor_1.default,
             {
+              key: `${contentType}-${schemaSelectionKey}`,
               action: (code) => dispatch((0, slice_1.setStringRawBody)(code)),
               language: language,
               required: required,
@@ -289,6 +424,7 @@ function Body({
             react_1.default.createElement(
               LiveEditor_1.default,
               {
+                key: `${contentType}-example`,
                 action: (code) => dispatch((0, slice_1.setStringRawBody)(code)),
                 language: language,
                 required: required,
@@ -319,6 +455,7 @@ function Body({
           react_1.default.createElement(
             LiveEditor_1.default,
             {
+              key: `${contentType}-${schemaSelectionKey}`,
               action: (code) => dispatch((0, slice_1.setStringRawBody)(code)),
               language: language,
               required: required,
@@ -326,31 +463,28 @@ function Body({
             defaultBody
           )
         ),
-        examplesBodies.map((example) => {
+        examplesBodies.map((ex) => {
           return (
             // @ts-ignore
             react_1.default.createElement(
               TabItem_1.default,
-              {
-                label: example.label,
-                value: example.label,
-                key: example.label,
-              },
-              example.summary &&
+              { label: ex.label, value: ex.label, key: ex.label },
+              ex.summary &&
                 react_1.default.createElement(
                   Markdown_1.default,
                   null,
-                  example.summary
+                  ex.summary
                 ),
-              example.body &&
+              ex.body &&
                 react_1.default.createElement(
                   LiveEditor_1.default,
                   {
+                    key: `${contentType}-${ex.label}`,
                     action: (code) =>
                       dispatch((0, slice_1.setStringRawBody)(code)),
                     language: language,
                   },
-                  example.body
+                  ex.body
                 )
             )
           );
@@ -364,6 +498,7 @@ function Body({
     react_1.default.createElement(
       LiveEditor_1.default,
       {
+        key: `${contentType}-${schemaSelectionKey}`,
         action: (code) => dispatch((0, slice_1.setStringRawBody)(code)),
         language: language,
         required: required,

package/lib/theme/ApiExplorer/Body/resolveSchemaWithSelections.d.ts

@@ -0,0 +1,13 @@
+import { SchemaObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+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 declare function resolveSchemaWithSelections(schema: SchemaObject | undefined, selections: SchemaSelections, basePath?: string): SchemaObject | undefined;

package/lib/theme/ApiExplorer/Body/resolveSchemaWithSelections.js

@@ -0,0 +1,133 @@
+"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.
+ * ========================================================================== */
+var __importDefault =
+  (this && this.__importDefault) ||
+  function (mod) {
+    return mod && mod.__esModule ? mod : { default: mod };
+  };
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSchemaWithSelections = resolveSchemaWithSelections;
+const merge_1 = __importDefault(require("lodash/merge"));
+/**
+ * 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
+ */
+function resolveSchemaWithSelections(
+  schema,
+  selections,
+  basePath = "requestBody"
+) {
+  if (!schema) {
+    return schema;
+  }
+  // Deep clone to avoid mutating the original schema
+  const schemaCopy = JSON.parse(JSON.stringify(schema));
+  return resolveSchemaRecursive(schemaCopy, selections, basePath);
+}
+function resolveSchemaRecursive(schema, selections, currentPath) {
+  // Handle oneOf
+  if (schema.oneOf && Array.isArray(schema.oneOf)) {
+    const selectedIndex = selections[currentPath] ?? 0;
+    const selectedSchema = schema.oneOf[selectedIndex];
+    if (selectedSchema) {
+      // If there are shared properties, merge them with the selected schema
+      if (schema.properties) {
+        const mergedSchema = (0, merge_1.default)({}, 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];
+    if (selectedSchema) {
+      // If there are shared properties, merge them with the selected schema
+      if (schema.properties) {
+        const mergedSchema = (0, merge_1.default)({}, 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,
+        selections,
+        `${currentPath}.allOf.${index}`
+      );
+    });
+    // Merge all resolved items
+    const mergedSchema = resolvedItems.reduce(
+      (acc, item) => (0, merge_1.default)(acc, item),
+      {}
+    );
+    // Preserve any top-level properties from the original schema
+    if (schema.properties) {
+      mergedSchema.properties = (0, merge_1.default)(
+        {},
+        mergedSchema.properties,
+        schema.properties
+      );
+    }
+    return mergedSchema;
+  }
+  // Handle object properties recursively
+  if (schema.properties) {
+    const resolvedProperties = {};
+    for (const [propName, propSchema] of Object.entries(schema.properties)) {
+      resolvedProperties[propName] = resolveSchemaRecursive(
+        propSchema,
+        selections,
+        `${currentPath}.${propName}`
+      );
+    }
+    schema.properties = resolvedProperties;
+  }
+  // Handle array items recursively
+  if (schema.items) {
+    schema.items = resolveSchemaRecursive(
+      schema.items,
+      selections,
+      `${currentPath}.items`
+    );
+  }
+  return schema;
+}

package/lib/theme/ApiExplorer/SchemaSelection/index.d.ts

@@ -0,0 +1,2 @@
+export { default as schemaSelectionReducer, setSchemaSelection, clearSchemaSelections, } from "./slice";
+export type { SchemaSelectionState } from "./slice";

package/lib/theme/ApiExplorer/SchemaSelection/index.js

@@ -0,0 +1,36 @@
+"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.
+ * ========================================================================== */
+var __importDefault =
+  (this && this.__importDefault) ||
+  function (mod) {
+    return mod && mod.__esModule ? mod : { default: mod };
+  };
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearSchemaSelections =
+  exports.setSchemaSelection =
+  exports.schemaSelectionReducer =
+    void 0;
+var slice_1 = require("./slice");
+Object.defineProperty(exports, "schemaSelectionReducer", {
+  enumerable: true,
+  get: function () {
+    return __importDefault(slice_1).default;
+  },
+});
+Object.defineProperty(exports, "setSchemaSelection", {
+  enumerable: true,
+  get: function () {
+    return slice_1.setSchemaSelection;
+  },
+});
+Object.defineProperty(exports, "clearSchemaSelections", {
+  enumerable: true,
+  get: function () {
+    return slice_1.clearSchemaSelections;
+  },
+});