docusaurus-theme-openapi-docs 4.7.1 → 5.0.0

package/lib/theme/SchemaTabs/index.js

@@ -233,25 +233,44 @@ function TabContent({ lazy, children, selectedValue }) {
   return react_1.default.createElement(
     "div",
     { className: "margin-top--md" },
-    childTabs.map((tabItem, i) =>
-      (0, react_1.cloneElement)(tabItem, {
-        key: i,
-        hidden: tabItem.props.value !== selectedValue,
-      })
-    )
+    childTabs
   );
 }
 function TabsComponent(props) {
-  const tabs = (0, internal_1.useTabs)(props);
+  const tabs = (0, internal_1.useTabsContextValue)(props);
   return react_1.default.createElement(
-    "div",
-    { className: "openapi-tabs__schema-container" },
-    react_1.default.createElement(TabList, { ...props, ...tabs }),
-    react_1.default.createElement(TabContent, { ...props, ...tabs })
+    internal_1.TabsProvider,
+    { value: tabs },
+    react_1.default.createElement(
+      "div",
+      { className: "openapi-tabs__schema-container" },
+      react_1.default.createElement(TabList, { ...props, ...tabs }),
+      react_1.default.createElement(TabContent, { ...props, ...tabs })
+    )
   );
 }
 function SchemaTabs(props) {
   const isBrowser = (0, useIsBrowser_1.default)();
+  const children = Array.isArray(props.children)
+    ? props.children.filter(Boolean)
+    : props.children
+      ? [props.children]
+      : [];
+  if (children.length === 0) {
+    return null;
+  }
+  let sanitizedChildren;
+  try {
+    sanitizedChildren = (0, internal_1.sanitizeTabsChildren)(children);
+  } catch {
+    return null;
+  }
+  if (
+    !sanitizedChildren ||
+    (Array.isArray(sanitizedChildren) && sanitizedChildren.length === 0)
+  ) {
+    return null;
+  }
   return react_1.default.createElement(
     TabsComponent,
     // Remount tabs after hydration
@@ -262,6 +281,6 @@ function SchemaTabs(props) {
       key: String(isBrowser),
       ...props,
     },
-    (0, internal_1.sanitizeTabsChildren)(props.children)
+    sanitizedChildren
   );
 }

package/lib/theme/styles.scss

@@ -9,6 +9,7 @@
 @use "./ApiExplorer/FloatingButton/FloatingButton";
 @use "./ApiExplorer/FormFileUpload/FormFileUpload";
 @use "./ApiExplorer/FormItem/FormItem";
+@use "./ApiExplorer/FormLabel/FormLabel";
 @use "./ApiExplorer/FormMultiSelect/FormMultiSelect";
 @use "./ApiExplorer/FormSelect/FormSelect";
 @use "./ApiExplorer/FormTextInput/FormTextInput";

package/lib/theme/translationIds.d.ts

@@ -60,6 +60,8 @@ export declare const OPENAPI_SCHEMA: {
     NO_SCHEMA: string;
 };
 export declare const OPENAPI_SCHEMA_ITEM: {
+    CHARACTERS: string;
+    NON_EMPTY: string;
     REQUIRED: string;
     DEPRECATED: string;
     NULLABLE: string;
@@ -71,6 +73,7 @@ export declare const OPENAPI_SCHEMA_ITEM: {
     ENUM_VALUE: string;
     ENUM_DESCRIPTION: string;
     POSSIBLE_VALUES: string;
+    EXPRESSION: string;
     ONE_OF: string;
     ANY_OF: string;
 };

package/lib/theme/translationIds.js

@@ -84,6 +84,8 @@ exports.OPENAPI_SCHEMA = {
   NO_SCHEMA: "theme.openapi.schema.noSchema",
 };
 exports.OPENAPI_SCHEMA_ITEM = {
+  CHARACTERS: "theme.openapi.schemaItem.characters",
+  NON_EMPTY: "theme.openapi.schemaItem.nonEmpty",
   REQUIRED: "theme.openapi.schemaItem.required",
   DEPRECATED: "theme.openapi.schemaItem.deprecated",
   NULLABLE: "theme.openapi.schemaItem.nullable",
@@ -95,6 +97,7 @@ exports.OPENAPI_SCHEMA_ITEM = {
   ENUM_VALUE: "theme.openapi.schemaItem.enumValue",
   ENUM_DESCRIPTION: "theme.openapi.schemaItem.enumDescription",
   POSSIBLE_VALUES: "theme.openapi.schemaItem.possibleValues",
+  EXPRESSION: "theme.openapi.schemaItem.expression",
   ONE_OF: "theme.openapi.schemaItem.oneOf",
   ANY_OF: "theme.openapi.schemaItem.anyOf",
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-theme-openapi-docs",
   "description": "OpenAPI theme for Docusaurus.",
-  "version": "4.7.1",
+  "version": "5.0.0",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,9 +28,9 @@
     "watch": "concurrently --names \"lib,lib-next,tsc\" --kill-others \"yarn babel:lib --watch\" \"yarn babel:lib-next --watch\" \"yarn tsc --watch\""
   },
   "devDependencies": {
-    "@docusaurus/theme-classic": "^3.5.0",
-    "@docusaurus/theme-common": "^3.5.0",
-    "@docusaurus/types": "^3.5.0",
+    "@docusaurus/theme-classic": "^3.10.0",
+    "@docusaurus/theme-common": "^3.10.0",
+    "@docusaurus/types": "^3.10.0",
     "@types/crypto-js": "^4.2.2",
     "@types/file-saver": "^2.0.7",
     "@types/lodash": "^4.17.20",
@@ -38,7 +38,7 @@
     "@types/postman-collection": "^3.5.11",
     "@types/react-modal": "^3.16.3",
     "concurrently": "^9.2.0",
-    "docusaurus-plugin-openapi-docs": "^4.7.1",
+    "docusaurus-plugin-openapi-docs": "^5.0.0",
     "docusaurus-plugin-sass": "^0.2.6",
     "eslint-plugin-prettier": "^5.5.1"
   },
@@ -53,6 +53,7 @@
     "file-saver": "^2.0.5",
     "lodash": "^4.17.21",
     "pako": "^2.1.0",
+    "path-browserify": "^1.0.1",
     "postman-code-generators": "^2.0.0",
     "postman-collection": "^5.0.2",
     "prism-react-renderer": "^2.4.1",
@@ -72,8 +73,8 @@
     "xml-formatter": "^3.6.6"
   },
   "peerDependencies": {
-    "@docusaurus/theme-common": "^3.5.0",
-    "docusaurus-plugin-openapi-docs": "^4.0.0",
+    "@docusaurus/theme-common": "^3.10.0",
+    "docusaurus-plugin-openapi-docs": "^5.0.0",
     "docusaurus-plugin-sass": "^0.2.3",
     "react": "^16.8.4 || ^17.0.0 || ^18.0.0 || ^19.0.0",
     "react-dom": "^16.8.4 || ^17.0.0 || ^18.0.0 || ^19.0.0"
@@ -81,5 +82,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "0a89b9db05458cff9591eb065160e26c05f64a18"
+  "gitHead": "516bd48c628fb16b7fe90d8f996168ab75ce5562"
 }

package/src/index.ts

@@ -42,6 +42,7 @@ export default function docusaurusThemeOpenAPI(): Plugin<void> {
           resolve: {
             fallback: {
               buffer: require.resolve("buffer/"),
+              path: require.resolve("path-browserify"),
             },
           },
           plugins: [
@@ -71,6 +72,7 @@ export default function docusaurusThemeOpenAPI(): Plugin<void> {
         resolve: {
           fallback: {
             buffer: require.resolve("buffer/"),
+            path: require.resolve("path-browserify"),
           },
         },
         plugins: [

package/src/markdown/schema.ts

@@ -10,6 +10,44 @@ import { translate } from "@docusaurus/Translate";
 import { OPENAPI_SCHEMA_ITEM } from "../theme/translationIds";
 import { SchemaObject } from "../types";
 
+/**
+ * Extracts enum values from a schema, including when wrapped in allOf.
+ */
+function getEnumFromSchema(schema: SchemaObject): any[] | undefined {
+  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: SchemaObject): string | undefined {
+  if (schema.type) {
+    return schema.type as string;
+  }
+
+  if (schema.allOf && Array.isArray(schema.allOf)) {
+    for (const item of schema.allOf) {
+      if (item.type) {
+        return item.type as string;
+      }
+    }
+  }
+
+  return undefined;
+}
+
 function prettyName(schema: SchemaObject, circular?: boolean) {
   // Handle enum-only schemas (valid in JSON Schema)
   // When enum is present without explicit type, treat as string
@@ -28,6 +66,12 @@ function prettyName(schema: SchemaObject, circular?: boolean) {
         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";
   }
 
@@ -92,11 +136,11 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
 
   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 as SchemaObject);
+    if (itemsEnum) {
+      qualifierGroups.push(`[${itemsEnum.map((e) => `\`${e}\``).join(", ")}]`);
     }
   }
 
@@ -104,14 +148,22 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
     let lengthQualifier = "";
     let minLength;
     let maxLength;
+    const charactersMessage = translate({
+      id: OPENAPI_SCHEMA_ITEM.CHARACTERS,
+      message: "characters",
+    });
+    const nonEmptyMessage = translate({
+      id: 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) {
@@ -165,9 +217,11 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
   }
 
   if (schema.pattern) {
-    qualifierGroups.push(
-      `Value must match regular expression \`${schema.pattern}\``
-    );
+    const expressionMessage = translate({
+      id: OPENAPI_SCHEMA_ITEM.EXPRESSION,
+      message: "Value must match regular expression",
+    });
+    qualifierGroups.push(`${expressionMessage} \`${schema.pattern}\``);
   }
 
   // Check if discriminator mapping
@@ -177,8 +231,10 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
     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) {

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

@@ -23,8 +23,9 @@ function Accept() {
   }
 
   return (
-    <FormItem label="Accept">
+    <FormItem>
       <FormSelect
+        label="Accept"
         value={value}
         options={options}
         onChange={(e: any) => dispatch(setAccept(e.target.value))}

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

@@ -34,13 +34,12 @@ function Authorization() {
   return (
     <div>
       {optionKeys.length > 1 && (
-        <FormItem
-          label={translate({
-            id: OPENAPI_AUTH.SECURITY_SCHEME,
-            message: "Security Scheme",
-          })}
-        >
+        <FormItem>
           <FormSelect
+            label={translate({
+              id: OPENAPI_AUTH.SECURITY_SCHEME,
+              message: "Security Scheme",
+            })}
             options={optionKeys}
             value={selected}
             onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
@@ -52,14 +51,12 @@ function Authorization() {
       {selectedAuth.map((a: any) => {
         if (a.type === "http" && a.scheme === "bearer") {
           return (
-            <FormItem
-              label={translate({
-                id: OPENAPI_AUTH.BEARER_TOKEN,
-                message: "Bearer Token",
-              })}
-              key={a.key + "-bearer"}
-            >
+            <FormItem key={a.key + "-bearer"}>
               <FormTextInput
+                label={translate({
+                  id: OPENAPI_AUTH.BEARER_TOKEN,
+                  message: "Bearer Token",
+                })}
                 placeholder={translate({
                   id: OPENAPI_AUTH.BEARER_TOKEN,
                   message: "Bearer Token",
@@ -83,14 +80,12 @@ function Authorization() {
 
         if (a.type === "oauth2") {
           return (
-            <FormItem
-              label={translate({
-                id: OPENAPI_AUTH.BEARER_TOKEN,
-                message: "Bearer Token",
-              })}
-              key={a.key + "-oauth2"}
-            >
+            <FormItem key={a.key + "-oauth2"}>
               <FormTextInput
+                label={translate({
+                  id: OPENAPI_AUTH.BEARER_TOKEN,
+                  message: "Bearer Token",
+                })}
                 placeholder={translate({
                   id: OPENAPI_AUTH.BEARER_TOKEN,
                   message: "Bearer Token",
@@ -115,13 +110,12 @@ function Authorization() {
         if (a.type === "http" && a.scheme === "basic") {
           return (
             <React.Fragment key={a.key + "-basic"}>
-              <FormItem
-                label={translate({
-                  id: OPENAPI_AUTH.USERNAME,
-                  message: "Username",
-                })}
-              >
+              <FormItem>
                 <FormTextInput
+                  label={translate({
+                    id: OPENAPI_AUTH.USERNAME,
+                    message: "Username",
+                  })}
                   placeholder={translate({
                     id: OPENAPI_AUTH.USERNAME,
                     message: "Username",
@@ -139,13 +133,12 @@ function Authorization() {
                   }}
                 />
               </FormItem>
-              <FormItem
-                label={translate({
-                  id: OPENAPI_AUTH.PASSWORD,
-                  message: "Password",
-                })}
-              >
+              <FormItem>
                 <FormTextInput
+                  label={translate({
+                    id: OPENAPI_AUTH.PASSWORD,
+                    message: "Password",
+                  })}
                   placeholder={translate({
                     id: OPENAPI_AUTH.PASSWORD,
                     message: "Password",
@@ -170,8 +163,9 @@ function Authorization() {
 
         if (a.type === "apiKey") {
           return (
-            <FormItem label={`${a.key}`} key={a.key + "-apikey"}>
+            <FormItem key={a.key + "-apikey"}>
               <FormTextInput
+                label={`${a.key}`}
                 placeholder={`${a.key}`}
                 password
                 value={data[a.key].apiKey ?? ""}

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

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

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

@@ -5,9 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import React from "react";
+import React, { useEffect, useState } from "react";
 
 import FormFileUpload from "@theme/ApiExplorer/FormFileUpload";
+import FormLabel from "@theme/ApiExplorer/FormLabel";
 import FormSelect from "@theme/ApiExplorer/FormSelect";
 import FormTextInput from "@theme/ApiExplorer/FormTextInput";
 import LiveApp from "@theme/ApiExplorer/LiveEditor";
@@ -16,70 +17,139 @@ import type { SchemaObject } from "docusaurus-plugin-openapi-docs/src/openapi/ty
 
 import FileArrayFormBodyItem from "../FileArrayFormBodyItem";
 import { clearFormBodyKey, setFileFormBody, setStringFormBody } from "../slice";
+import { setFieldEncoding } from "../../EncodingSelection/slice";
 
 interface FormBodyItemProps {
   schemaObject: SchemaObject;
   id: string;
   schema: SchemaObject;
+  label?: string;
+  required?: boolean;
+  exampleValue?: SchemaObject["example"];
+  fieldEncoding?: string;
 }
 
 export default function FormBodyItem({
   schemaObject,
   id,
   schema,
+  label,
+  required,
+  exampleValue,
+  fieldEncoding,
 }: FormBodyItemProps): React.JSX.Element {
   const dispatch = 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] = useState<string>(
+    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.
+  useEffect(() => {
+    if (encodingOptions[0]) {
+      dispatch(
+        setFieldEncoding({ field: id, contentType: encodingOptions[0] })
+      );
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  const [value, setValue] = useState(() => {
+    let initialValue = exampleValue ?? "";
+
+    if (schemaObject.type === "object" && exampleValue) {
+      initialValue = JSON.stringify(exampleValue, null, 2);
+    }
+
+    return initialValue;
+  });
+
+  useEffect(() => {
+    if (value) {
+      dispatch(setStringFormBody({ key: id, value }));
+    } else {
+      dispatch(clearFormBodyKey(id));
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   if (
     schemaObject.type === "array" &&
     schemaObject.items?.format === "binary"
   ) {
     return (
-      <FileArrayFormBodyItem id={id} description={schemaObject.description} />
+      <>
+        {label && <FormLabel label={label} required={required} />}
+        <FileArrayFormBodyItem id={id} description={schemaObject.description} />
+      </>
     );
   }
 
   if (schemaObject.format === "binary") {
     return (
-      <FormFileUpload
-        placeholder={schemaObject.description || id}
-        onChange={(file: any) => {
-          if (file === undefined) {
-            dispatch(clearFormBodyKey(id));
-            return;
-          }
-          dispatch(
-            setFileFormBody({
-              key: id,
-              value: {
-                src: `/path/to/${file.name}`,
-                content: file,
-              },
-            })
-          );
-        }}
-      />
+      <>
+        {label && <FormLabel label={label} required={required} />}
+        {hasMultipleEncodings && (
+          <div style={{ marginTop: "0.5rem" }}>
+            <FormSelect
+              label="Content-Type"
+              options={encodingOptions}
+              value={selectedEncoding}
+              onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
+                const ct = e.target.value;
+                setSelectedEncoding(ct);
+                dispatch(setFieldEncoding({ field: id, contentType: ct }));
+              }}
+            />
+          </div>
+        )}
+        <FormFileUpload
+          placeholder={schemaObject.description || id}
+          onChange={(file: any) => {
+            if (file === undefined) {
+              dispatch(clearFormBodyKey(id));
+              return;
+            }
+            dispatch(
+              setFileFormBody({
+                key: id,
+                value: {
+                  src: `/path/to/${file.name}`,
+                  content: file,
+                },
+              })
+            );
+          }}
+        />
+      </>
     );
   }
 
-  if (
-    schemaObject.type === "object" &&
-    (schemaObject.example || schemaObject.examples)
-  ) {
-    const objectExample = JSON.stringify(
-      schemaObject.example ?? schemaObject.examples[0],
-      null,
-      2
-    );
-
+  if (schemaObject.type === "object") {
     return (
-      <LiveApp
-        action={(code: string) =>
-          dispatch(setStringFormBody({ key: id, value: code }))
-        }
-      >
-        {objectExample}
-      </LiveApp>
+      <>
+        {label && <FormLabel label={label} required={required} />}
+        <LiveApp
+          action={(code: string) =>
+            dispatch(setStringFormBody({ key: id, value: code }))
+          }
+        >
+          {value}
+        </LiveApp>
+      </>
     );
   }
 
@@ -89,9 +159,13 @@ export default function FormBodyItem({
   ) {
     return (
       <FormSelect
+        label={label}
+        required={required}
+        value={value}
         options={["---", ...schemaObject.enum]}
         onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
           const val = e.target.value;
+          setValue(val);
           if (val === "---") {
             dispatch(clearFormBodyKey(id));
           } else {
@@ -109,12 +183,16 @@ export default function FormBodyItem({
   // TODO: support all the other types.
   return (
     <FormTextInput
+      label={label}
+      required={required}
+      value={value}
       paramName={id}
       isRequired={
         Array.isArray(schema.required) && schema.required.includes(id)
       }
       placeholder={schemaObject.description || id}
       onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
+        setValue(e.target.value);
         dispatch(setStringFormBody({ key: id, value: e.target.value }));
       }}
     />