docusaurus-theme-openapi-docs 4.7.0 → 5.0.0

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/Authorization/slice.ts

@@ -7,7 +7,7 @@
 
 import { createSlice, PayloadAction } from "@reduxjs/toolkit";
 import { createStorage, hashArray } from "@theme/ApiExplorer/storage-utils";
-import {
+import type {
   SecurityRequirementObject,
   SecuritySchemeObject,
 } from "docusaurus-plugin-openapi-docs/src/openapi/types";

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

@@ -6,8 +6,10 @@
  * ========================================================================== */
 
 import React, { useState } from "react";
+
 import FormFileUpload from "@theme/ApiExplorer/FormFileUpload";
 import { useTypedDispatch } from "@theme/ApiItem/hooks";
+
 import { FileContent, setFileArrayFormBody } from "../slice";
 
 interface FileArrayFormItemProps {
@@ -41,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,79 +5,151 @@
  * 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";
 import { useTypedDispatch } from "@theme/ApiItem/hooks";
-import { SchemaObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
-import { clearFormBodyKey, setFileFormBody, setStringFormBody } from "../slice";
+import type { SchemaObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+
 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>
+      </>
     );
   }
 
@@ -87,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 {
@@ -107,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 }));
       }}
     />

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

@@ -8,7 +8,6 @@
 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";
@@ -18,13 +17,13 @@ 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 { sampleFromSchema } from "docusaurus-plugin-openapi-docs/lib/openapi/createSchemaExample";
+import type { RequestBodyObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
 import format from "xml-formatter";
 
-import { clearRawBody, setFileRawBody, setStringRawBody } from "./slice";
 import FormBodyItem from "./FormBodyItem";
 import { resolveSchemaWithSelections } from "./resolveSchemaWithSelections";
+import { clearRawBody, setFileRawBody, setStringRawBody } from "./slice";
 
 export interface Props {
   jsonRequestBodyExample: string;
@@ -94,6 +93,8 @@ function Body({
   const rawSchema = requestBodyMetadata?.content?.[contentType]?.schema;
   const example = requestBodyMetadata?.content?.[contentType]?.example;
   const examples = requestBodyMetadata?.content?.[contentType]?.examples;
+  const encoding: Record<string, { contentType?: string }> | undefined =
+    requestBodyMetadata?.content?.[contentType]?.encoding;
 
   // Resolve the schema based on user's anyOf/oneOf tab selections
   const schema = useMemo(() => {
@@ -317,23 +318,89 @@ function Body({
   ) {
     return (
       <FormItem className="openapi-explorer__form-item-body-container">
-        {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>
-          );
-        })}
+        <SchemaTabs className="openapi-tabs__schema" lazy>
+          {/* @ts-ignore */}
+          <TabItem
+            label={translate({
+              id: OPENAPI_BODY.EXAMPLE_FROM_SCHEMA,
+              message: "Example (from schema)",
+            })}
+            value="Example (from schema)"
+            default
+          >
+            {Object.entries(schema.properties ?? {}).map(([key, val]: any) => {
+              return (
+                <FormItem key={key}>
+                  <FormBodyItem
+                    schemaObject={val}
+                    id={key}
+                    schema={schema}
+                    exampleValue={val.example}
+                    label={key}
+                    required={
+                      Array.isArray(schema.required) &&
+                      schema.required.includes(key)
+                    }
+                    fieldEncoding={encoding?.[key]?.contentType}
+                  ></FormBodyItem>
+                </FormItem>
+              );
+            })}
+          </TabItem>
+          {example && (
+            // @ts-ignore
+            <TabItem label="Example" value="example">
+              {Object.entries(schema.properties ?? {}).map(
+                ([schemaKey, schemaVal]: any) => {
+                  return (
+                    <FormItem key={schemaKey}>
+                      <FormBodyItem
+                        schemaObject={schemaVal}
+                        id={schemaKey}
+                        schema={schema}
+                        exampleValue={example[schemaKey]}
+                        label={schemaKey}
+                        required={
+                          Array.isArray(schema.required) &&
+                          schema.required.includes(schemaKey)
+                        }
+                        fieldEncoding={encoding?.[schemaKey]?.contentType}
+                      ></FormBodyItem>
+                    </FormItem>
+                  );
+                }
+              )}
+            </TabItem>
+          )}
+          {examples &&
+            Object.entries(examples).map(([key, value]) => {
+              return (
+                // @ts-ignore
+                <TabItem label={key} value={key} key={key}>
+                  {Object.entries(schema.properties ?? {}).map(
+                    ([schemaKey, schemaVal]: any) => {
+                      return (
+                        <FormItem key={schemaKey}>
+                          <FormBodyItem
+                            schemaObject={schemaVal}
+                            id={schemaKey}
+                            schema={schema}
+                            exampleValue={value.value?.[schemaKey]}
+                            label={schemaKey}
+                            required={
+                              Array.isArray(schema.required) &&
+                              schema.required.includes(schemaKey)
+                            }
+                            fieldEncoding={encoding?.[schemaKey]?.contentType}
+                          ></FormBodyItem>
+                        </FormItem>
+                      );
+                    }
+                  )}
+                </TabItem>
+              );
+            })}
+        </SchemaTabs>
       </FormItem>
     );
   }

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

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import { SchemaObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import type { SchemaObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
 import merge from "lodash/merge";
 
 export interface SchemaSelections {

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

@@ -11,6 +11,7 @@ import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
 import ApiCodeBlock from "@theme/ApiExplorer/ApiCodeBlock";
 import buildPostmanRequest from "@theme/ApiExplorer/buildPostmanRequest";
 import CodeTabs from "@theme/ApiExplorer/CodeTabs";
+import { useResolvedEncoding } from "@theme/ApiExplorer/EncodingSelection/useResolvedEncoding";
 import { useTypedSelector } from "@theme/ApiItem/hooks";
 import cloneDeep from "lodash/cloneDeep";
 import codegen from "postman-code-generators";
@@ -30,6 +31,7 @@ export interface Props {
   postman: sdk.Request;
   codeSamples: CodeSample[];
   maskCredentials?: boolean;
+  requestBody?: import("docusaurus-plugin-openapi-docs/src/openapi/types").RequestBodyObject;
 }
 
 function CodeTab({ children, hidden, className }: any): React.JSX.Element {
@@ -44,6 +46,7 @@ function CodeSnippets({
   postman,
   codeSamples,
   maskCredentials: propMaskCredentials,
+  requestBody,
 }: Props) {
   const { siteConfig } = useDocusaurusContext();
 
@@ -76,7 +79,9 @@ function CodeSnippets({
               const authOptions =
                 clonedAuth?.options?.[key] ??
                 clonedAuth?.options?.[comboAuthId];
-              placeholder = authOptions?.find((opt: any) => opt.key === key)?.name;
+              placeholder = authOptions?.find(
+                (opt: any) => opt.key === key
+              )?.name;
               obj[key] = cleanCredentials(obj[key]);
             } else {
               obj[key] = `<${placeholder ?? key}>`;
@@ -93,6 +98,8 @@ function CodeSnippets({
       })()
     : auth;
 
+  const encoding = useResolvedEncoding(requestBody);
+
   // Create a Postman request object using cleanedAuth or original auth
   const cleanedPostmanRequest = buildPostmanRequest(postman, {
     queryParams,
@@ -104,6 +111,7 @@ function CodeSnippets({
     body,
     server,
     auth: cleanedAuth,
+    encoding,
   });
 
   // User-defined languages array

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

@@ -9,11 +9,12 @@ import React, { cloneElement, ReactElement, useEffect, useRef } from "react";
 
 import {
   sanitizeTabsChildren,
+  type TabItemProps,
   type TabProps,
+  TabsProvider,
   useScrollPositionBlocker,
-  useTabs,
+  useTabsContextValue,
 } from "@docusaurus/theme-common/internal";
-import { TabItemProps } from "@docusaurus/theme-common/lib/utils/tabsUtils";
 import useIsBrowser from "@docusaurus/useIsBrowser";
 import clsx from "clsx";
 
@@ -43,7 +44,7 @@ function TabList({
   selectedValue,
   selectValue,
   tabValues,
-}: CodeTabsProps & ReturnType<typeof useTabs>) {
+}: CodeTabsProps & ReturnType<typeof useTabsContextValue>) {
   const tabRefs = useRef<(HTMLLIElement | null)[]>([]);
   const tabsScrollContainerRef = useRef<any>(null);
   const { blockElementScrollPositionUntilNextRender } =
@@ -192,7 +193,8 @@ function TabContent({
   lazy,
   children,
   selectedValue,
-}: CodeTabsProps & ReturnType<typeof useTabs>): React.JSX.Element | null {
+}: CodeTabsProps &
+  ReturnType<typeof useTabsContextValue>): React.JSX.Element | null {
   const childTabs = (Array.isArray(children) ? children : [children]).filter(
     Boolean
   ) as ReactElement<TabItemProps>[];
@@ -207,28 +209,26 @@ function TabContent({
     return cloneElement(selectedTabItem, { className: "margin-top--md" });
   }
   return (
-    <div className="margin-top--md openapi-tabs__code-content">
-      {childTabs.map((tabItem, i) =>
-        cloneElement(tabItem, {
-          key: i,
-          hidden: tabItem.props.value !== selectedValue,
-        })
-      )}
-    </div>
+    <div className="margin-top--md openapi-tabs__code-content">{childTabs}</div>
   );
 }
 
 function TabsComponent(props: CodeTabsProps & Props): React.JSX.Element {
-  const tabs = useTabs(props);
+  const tabs = useTabsContextValue(props);
   const { className } = props;
 
   return (
-    <div
-      className={clsx("tabs-container openapi-tabs__code-container", className)}
-    >
-      <TabList {...props} {...tabs} />
-      <TabContent {...props} {...tabs} />
-    </div>
+    <TabsProvider value={tabs}>
+      <div
+        className={clsx(
+          "tabs-container openapi-tabs__code-container",
+          className
+        )}
+      >
+        <TabList {...props} {...tabs} />
+        <TabContent {...props} {...tabs} />
+      </div>
+    </TabsProvider>
   );
 }
 

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

@@ -12,6 +12,7 @@ import FormSelect from "@theme/ApiExplorer/FormSelect";
 import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
 
 import { setContentType } from "./slice";
+import { clearEncodingSelection } from "@theme/ApiExplorer/EncodingSelection/slice";
 
 function ContentType() {
   const value = useTypedSelector((state: any) => state.contentType.value);
@@ -23,13 +24,15 @@ function ContentType() {
   }
 
   return (
-    <FormItem label="Content-Type">
+    <FormItem>
       <FormSelect
+        label="Content-Type"
         value={value}
         options={options}
-        onChange={(e: React.ChangeEvent<HTMLSelectElement>) =>
-          dispatch(setContentType(e.target.value))
-        }
+        onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
+          dispatch(setContentType(e.target.value));
+          dispatch(clearEncodingSelection());
+        }}
       />
     </FormItem>
   );