docusaurus-theme-openapi-docs 4.7.0 → 5.0.0

package/lib/index.js

@@ -38,6 +38,7 @@ function docusaurusThemeOpenAPI() {
                     resolve: {
                         fallback: {
                             buffer: require.resolve("buffer/"),
+                            path: require.resolve("path-browserify"),
                         },
                     },
                     plugins: [
@@ -67,6 +68,7 @@ function docusaurusThemeOpenAPI() {
                 resolve: {
                     fallback: {
                         buffer: require.resolve("buffer/"),
+                        path: require.resolve("path-browserify"),
                     },
                 },
                 plugins: [

package/lib/markdown/schema.js

@@ -10,6 +10,38 @@ exports.getSchemaName = getSchemaName;
 exports.getQualifierMessage = getQualifierMessage;
 const Translate_1 = require("@docusaurus/Translate");
 const translationIds_1 = require("../theme/translationIds");
+/**
+ * Extracts enum values from a schema, including when wrapped in allOf.
+ */
+function getEnumFromSchema(schema) {
+    if (schema.enum) {
+        return schema.enum;
+    }
+    if (schema.allOf && Array.isArray(schema.allOf)) {
+        for (const item of schema.allOf) {
+            if (item.enum) {
+                return item.enum;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Extracts the type from a schema, including when wrapped in allOf.
+ */
+function getTypeFromSchema(schema) {
+    if (schema.type) {
+        return schema.type;
+    }
+    if (schema.allOf && Array.isArray(schema.allOf)) {
+        for (const item of schema.allOf) {
+            if (item.type) {
+                return item.type;
+            }
+        }
+    }
+    return undefined;
+}
 function prettyName(schema, circular) {
     // Handle enum-only schemas (valid in JSON Schema)
     // When enum is present without explicit type, treat as string
@@ -26,6 +58,12 @@ function prettyName(schema, circular) {
                 return schema.allOf[0];
             }
         }
+        // Check if allOf contains an enum - if so, return the type from allOf
+        const enumFromAllOf = getEnumFromSchema(schema);
+        if (enumFromAllOf) {
+            const typeFromAllOf = getTypeFromSchema(schema);
+            return typeFromAllOf ?? "string";
+        }
         return "object";
     }
     if (schema.oneOf) {
@@ -72,23 +110,33 @@ function getQualifierMessage(schema) {
         message: "Possible values:",
     })}** `;
     let qualifierGroups = [];
-    if (schema.items && schema.items.enum) {
-        if (schema.items.enum) {
-            qualifierGroups.push(`[${schema.items.enum.map((e) => `\`${e}\``).join(", ")}]`);
+    // Check for enum in array items (directly or inside allOf)
+    if (schema.items) {
+        const itemsEnum = getEnumFromSchema(schema.items);
+        if (itemsEnum) {
+            qualifierGroups.push(`[${itemsEnum.map((e) => `\`${e}\``).join(", ")}]`);
         }
     }
     if (schema.minLength || schema.maxLength) {
         let lengthQualifier = "";
         let minLength;
         let maxLength;
+        const charactersMessage = (0, Translate_1.translate)({
+            id: translationIds_1.OPENAPI_SCHEMA_ITEM.CHARACTERS,
+            message: "characters",
+        });
+        const nonEmptyMessage = (0, Translate_1.translate)({
+            id: translationIds_1.OPENAPI_SCHEMA_ITEM.NON_EMPTY,
+            message: "non-empty",
+        });
         if (schema.minLength && schema.minLength > 1) {
-            minLength = `\`>= ${schema.minLength} characters\``;
+            minLength = `\`>= ${schema.minLength} ${charactersMessage}\``;
         }
         if (schema.minLength && schema.minLength === 1) {
-            minLength = `\`non-empty\``;
+            minLength = `\`${nonEmptyMessage}\``;
         }
         if (schema.maxLength) {
-            maxLength = `\`<= ${schema.maxLength} characters\``;
+            maxLength = `\`<= ${schema.maxLength} ${charactersMessage}\``;
         }
         if (minLength && !maxLength) {
             lengthQualifier += minLength;
@@ -138,7 +186,11 @@ function getQualifierMessage(schema) {
         qualifierGroups.push(minmaxQualifier);
     }
     if (schema.pattern) {
-        qualifierGroups.push(`Value must match regular expression \`${schema.pattern}\``);
+        const expressionMessage = (0, Translate_1.translate)({
+            id: translationIds_1.OPENAPI_SCHEMA_ITEM.EXPRESSION,
+            message: "Value must match regular expression",
+        });
+        qualifierGroups.push(`${expressionMessage} \`${schema.pattern}\``);
     }
     // Check if discriminator mapping
     const discriminator = schema;
@@ -146,8 +198,10 @@ function getQualifierMessage(schema) {
         const values = Object.keys(discriminator.mapping);
         qualifierGroups.push(`[${values.map((e) => `\`${e}\``).join(", ")}]`);
     }
-    if (schema.enum) {
-        qualifierGroups.push(`[${schema.enum.map((e) => `\`${e}\``).join(", ")}]`);
+    // Check for enum directly on schema or inside allOf
+    const schemaEnum = getEnumFromSchema(schema);
+    if (schemaEnum) {
+        qualifierGroups.push(`[${schemaEnum.map((e) => `\`${e}\``).join(", ")}]`);
     }
     if (schema.minItems) {
         qualifierGroups.push(`\`>= ${schema.minItems}\``);

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

@@ -27,8 +27,9 @@ function Accept() {
   }
   return react_1.default.createElement(
     FormItem_1.default,
-    { label: "Accept" },
+    null,
     react_1.default.createElement(FormSelect_1.default, {
+      label: "Accept",
       value: value,
       options: options,
       onChange: (e) => dispatch((0, slice_1.setAccept)(e.target.value)),

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

@@ -39,13 +39,12 @@ function Authorization() {
     optionKeys.length > 1 &&
       react_1.default.createElement(
         FormItem_1.default,
-        {
+        null,
+        react_1.default.createElement(FormSelect_1.default, {
           label: (0, Translate_1.translate)({
             id: translationIds_1.OPENAPI_AUTH.SECURITY_SCHEME,
             message: "Security Scheme",
           }),
-        },
-        react_1.default.createElement(FormSelect_1.default, {
           options: optionKeys,
           value: selected,
           onChange: (e) => {
@@ -57,14 +56,12 @@ function Authorization() {
       if (a.type === "http" && a.scheme === "bearer") {
         return react_1.default.createElement(
           FormItem_1.default,
-          {
+          { key: a.key + "-bearer" },
+          react_1.default.createElement(FormTextInput_1.default, {
             label: (0, Translate_1.translate)({
               id: translationIds_1.OPENAPI_AUTH.BEARER_TOKEN,
               message: "Bearer Token",
             }),
-            key: a.key + "-bearer",
-          },
-          react_1.default.createElement(FormTextInput_1.default, {
             placeholder: (0, Translate_1.translate)({
               id: translationIds_1.OPENAPI_AUTH.BEARER_TOKEN,
               message: "Bearer Token",
@@ -87,14 +84,12 @@ function Authorization() {
       if (a.type === "oauth2") {
         return react_1.default.createElement(
           FormItem_1.default,
-          {
+          { key: a.key + "-oauth2" },
+          react_1.default.createElement(FormTextInput_1.default, {
             label: (0, Translate_1.translate)({
               id: translationIds_1.OPENAPI_AUTH.BEARER_TOKEN,
               message: "Bearer Token",
             }),
-            key: a.key + "-oauth2",
-          },
-          react_1.default.createElement(FormTextInput_1.default, {
             placeholder: (0, Translate_1.translate)({
               id: translationIds_1.OPENAPI_AUTH.BEARER_TOKEN,
               message: "Bearer Token",
@@ -120,13 +115,12 @@ function Authorization() {
           { key: a.key + "-basic" },
           react_1.default.createElement(
             FormItem_1.default,
-            {
+            null,
+            react_1.default.createElement(FormTextInput_1.default, {
               label: (0, Translate_1.translate)({
                 id: translationIds_1.OPENAPI_AUTH.USERNAME,
                 message: "Username",
               }),
-            },
-            react_1.default.createElement(FormTextInput_1.default, {
               placeholder: (0, Translate_1.translate)({
                 id: translationIds_1.OPENAPI_AUTH.USERNAME,
                 message: "Username",
@@ -146,13 +140,12 @@ function Authorization() {
           ),
           react_1.default.createElement(
             FormItem_1.default,
-            {
+            null,
+            react_1.default.createElement(FormTextInput_1.default, {
               label: (0, Translate_1.translate)({
                 id: translationIds_1.OPENAPI_AUTH.PASSWORD,
                 message: "Password",
               }),
-            },
-            react_1.default.createElement(FormTextInput_1.default, {
               placeholder: (0, Translate_1.translate)({
                 id: translationIds_1.OPENAPI_AUTH.PASSWORD,
                 message: "Password",
@@ -176,8 +169,9 @@ function Authorization() {
       if (a.type === "apiKey") {
         return react_1.default.createElement(
           FormItem_1.default,
-          { label: `${a.key}`, key: a.key + "-apikey" },
+          { key: a.key + "-apikey" },
           react_1.default.createElement(FormTextInput_1.default, {
+            label: `${a.key}`,
             placeholder: `${a.key}`,
             password: true,
             value: data[a.key].apiKey ?? "",

package/lib/theme/ApiExplorer/Authorization/slice.d.ts

@@ -1,5 +1,5 @@
 import { PayloadAction } from "@reduxjs/toolkit";
-import { SecurityRequirementObject, SecuritySchemeObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import type { SecurityRequirementObject, SecuritySchemeObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
 import { ThemeConfig } from "docusaurus-theme-openapi-docs/src/types";
 export declare function createAuth({ security, securitySchemes, options: opts, }: {
     security?: SecurityRequirementObject[];

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

@@ -92,10 +92,6 @@ function FileArrayFormBodyItem({ id, description }) {
       );
       return;
     }
-    let maxIndex = 0;
-    newItems.keys().forEach((item) => {
-      maxIndex = item > maxIndex ? item : maxIndex;
-    });
     newItems.set(index, {
       src: `/path/to/${file.name}`,
       content: file,

package/lib/theme/ApiExplorer/Body/FormBodyItem/index.d.ts

@@ -1,9 +1,13 @@
 import React from "react";
-import { SchemaObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import type { SchemaObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
 interface FormBodyItemProps {
     schemaObject: SchemaObject;
     id: string;
     schema: SchemaObject;
+    label?: string;
+    required?: boolean;
+    exampleValue?: SchemaObject["example"];
+    fieldEncoding?: string;
 }
-export default function FormBodyItem({ schemaObject, id, schema, }: FormBodyItemProps): React.JSX.Element;
+export default function FormBodyItem({ schemaObject, id, schema, label, required, exampleValue, fieldEncoding, }: FormBodyItemProps): React.JSX.Element;
 export {};

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

@@ -5,6 +5,62 @@
  * 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) {
@@ -12,67 +68,156 @@ var __importDefault =
   };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = FormBodyItem;
-const react_1 = __importDefault(require("react"));
+const react_1 = __importStar(require("react"));
 const FormFileUpload_1 = __importDefault(
   require("@theme/ApiExplorer/FormFileUpload")
 );
+const FormLabel_1 = __importDefault(require("@theme/ApiExplorer/FormLabel"));
 const FormSelect_1 = __importDefault(require("@theme/ApiExplorer/FormSelect"));
 const FormTextInput_1 = __importDefault(
   require("@theme/ApiExplorer/FormTextInput")
 );
 const LiveEditor_1 = __importDefault(require("@theme/ApiExplorer/LiveEditor"));
 const hooks_1 = require("@theme/ApiItem/hooks");
-const slice_1 = require("../slice");
 const FileArrayFormBodyItem_1 = __importDefault(
   require("../FileArrayFormBodyItem")
 );
-function FormBodyItem({ schemaObject, id, schema }) {
+const slice_1 = require("../slice");
+const slice_2 = require("../../EncodingSelection/slice");
+function FormBodyItem({
+  schemaObject,
+  id,
+  schema,
+  label,
+  required,
+  exampleValue,
+  fieldEncoding,
+}) {
   const dispatch = (0, hooks_1.useTypedDispatch)();
+  // Parse comma-separated encoding contentType into selectable options
+  const encodingOptions = fieldEncoding
+    ? fieldEncoding
+        .split(",")
+        .map((t) => t.trim())
+        .filter(Boolean)
+    : [];
+  const hasMultipleEncodings = encodingOptions.length > 1;
+  // Initialize with the first declared content type
+  const [selectedEncoding, setSelectedEncoding] = (0, react_1.useState)(
+    encodingOptions[0] ?? ""
+  );
+  // Seed Redux with the first declared encoding on mount so the code snippet
+  // reflects a content type immediately, even before the user interacts.
+  // The empty dep array is intentional: `fieldEncoding` comes from a static
+  // spec value that never changes for the lifetime of this component instance,
+  // and re-seeding on every render would fight user selections.
+  (0, react_1.useEffect)(() => {
+    if (encodingOptions[0]) {
+      dispatch(
+        (0, slice_2.setFieldEncoding)({
+          field: id,
+          contentType: encodingOptions[0],
+        })
+      );
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  const [value, setValue] = (0, react_1.useState)(() => {
+    let initialValue = exampleValue ?? "";
+    if (schemaObject.type === "object" && exampleValue) {
+      initialValue = JSON.stringify(exampleValue, null, 2);
+    }
+    return initialValue;
+  });
+  (0, react_1.useEffect)(() => {
+    if (value) {
+      dispatch((0, slice_1.setStringFormBody)({ key: id, value }));
+    } else {
+      dispatch((0, slice_1.clearFormBodyKey)(id));
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
   if (
     schemaObject.type === "array" &&
     schemaObject.items?.format === "binary"
   ) {
-    return react_1.default.createElement(FileArrayFormBodyItem_1.default, {
-      id: id,
-      description: schemaObject.description,
-    });
+    return react_1.default.createElement(
+      react_1.default.Fragment,
+      null,
+      label &&
+        react_1.default.createElement(FormLabel_1.default, {
+          label: label,
+          required: required,
+        }),
+      react_1.default.createElement(FileArrayFormBodyItem_1.default, {
+        id: id,
+        description: schemaObject.description,
+      })
+    );
   }
   if (schemaObject.format === "binary") {
-    return react_1.default.createElement(FormFileUpload_1.default, {
-      placeholder: schemaObject.description || id,
-      onChange: (file) => {
-        if (file === undefined) {
-          dispatch((0, slice_1.clearFormBodyKey)(id));
-          return;
-        }
-        dispatch(
-          (0, slice_1.setFileFormBody)({
-            key: id,
-            value: {
-              src: `/path/to/${file.name}`,
-              content: file,
+    return react_1.default.createElement(
+      react_1.default.Fragment,
+      null,
+      label &&
+        react_1.default.createElement(FormLabel_1.default, {
+          label: label,
+          required: required,
+        }),
+      hasMultipleEncodings &&
+        react_1.default.createElement(
+          "div",
+          { style: { marginTop: "0.5rem" } },
+          react_1.default.createElement(FormSelect_1.default, {
+            label: "Content-Type",
+            options: encodingOptions,
+            value: selectedEncoding,
+            onChange: (e) => {
+              const ct = e.target.value;
+              setSelectedEncoding(ct);
+              dispatch(
+                (0, slice_2.setFieldEncoding)({ field: id, contentType: ct })
+              );
             },
           })
-        );
-      },
-    });
-  }
-  if (
-    schemaObject.type === "object" &&
-    (schemaObject.example || schemaObject.examples)
-  ) {
-    const objectExample = JSON.stringify(
-      schemaObject.example ?? schemaObject.examples[0],
-      null,
-      2
+        ),
+      react_1.default.createElement(FormFileUpload_1.default, {
+        placeholder: schemaObject.description || id,
+        onChange: (file) => {
+          if (file === undefined) {
+            dispatch((0, slice_1.clearFormBodyKey)(id));
+            return;
+          }
+          dispatch(
+            (0, slice_1.setFileFormBody)({
+              key: id,
+              value: {
+                src: `/path/to/${file.name}`,
+                content: file,
+              },
+            })
+          );
+        },
+      })
     );
+  }
+  if (schemaObject.type === "object") {
     return react_1.default.createElement(
-      LiveEditor_1.default,
-      {
-        action: (code) =>
-          dispatch((0, slice_1.setStringFormBody)({ key: id, value: code })),
-      },
-      objectExample
+      react_1.default.Fragment,
+      null,
+      label &&
+        react_1.default.createElement(FormLabel_1.default, {
+          label: label,
+          required: required,
+        }),
+      react_1.default.createElement(
+        LiveEditor_1.default,
+        {
+          action: (code) =>
+            dispatch((0, slice_1.setStringFormBody)({ key: id, value: code })),
+        },
+        value
+      )
     );
   }
   if (
@@ -80,9 +225,13 @@ function FormBodyItem({ schemaObject, id, schema }) {
     schemaObject.enum.every((value) => typeof value === "string")
   ) {
     return react_1.default.createElement(FormSelect_1.default, {
+      label: label,
+      required: required,
+      value: value,
       options: ["---", ...schemaObject.enum],
       onChange: (e) => {
         const val = e.target.value;
+        setValue(val);
         if (val === "---") {
           dispatch((0, slice_1.clearFormBodyKey)(id));
         } else {
@@ -98,10 +247,14 @@ function FormBodyItem({ schemaObject, id, schema }) {
   }
   // TODO: support all the other types.
   return react_1.default.createElement(FormTextInput_1.default, {
+    label: label,
+    required: required,
+    value: value,
     paramName: id,
     isRequired: Array.isArray(schema.required) && schema.required.includes(id),
     placeholder: schemaObject.description || id,
     onChange: (e) => {
+      setValue(e.target.value);
       dispatch(
         (0, slice_1.setStringFormBody)({ key: id, value: e.target.value })
       );

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

@@ -1,5 +1,5 @@
 import React from "react";
-import { RequestBodyObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import type { RequestBodyObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
 export interface Props {
     jsonRequestBodyExample: string;
     requestBodyMetadata?: RequestBodyObject;