docusaurus-theme-openapi-docs 4.7.1 → 5.0.0

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

@@ -93,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(() => {
@@ -316,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/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>
   );

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

@@ -0,0 +1,31 @@
+/* ============================================================================
+ * 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";
+
+// Maps form field name → user-selected content type
+export type State = Record<string, string>;
+
+const initialState: State = {};
+
+export const slice = createSlice({
+  name: "encodingSelection",
+  initialState,
+  reducers: {
+    setFieldEncoding: (
+      state,
+      action: PayloadAction<{ field: string; contentType: string }>
+    ) => {
+      state[action.payload.field] = action.payload.contentType;
+    },
+    clearEncodingSelection: () => initialState,
+  },
+});
+
+export const { setFieldEncoding, clearEncodingSelection } = slice.actions;
+
+export default slice.reducer;

package/src/theme/ApiExplorer/EncodingSelection/useResolvedEncoding.ts

@@ -0,0 +1,43 @@
+/* ============================================================================
+ * 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 { useTypedSelector } from "@theme/ApiItem/hooks";
+import type { RequestBodyObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+
+/**
+ * Merges the spec-declared `encoding` for the active content type with any
+ * per-field content-type selections the user has made in the UI.  User picks
+ * take precedence over the spec default.
+ *
+ * Returns `undefined` when no encoding is declared for the current content
+ * type so callers can skip the encoding path entirely.
+ */
+export function useResolvedEncoding(
+  requestBody: RequestBodyObject | undefined
+): Record<string, { contentType?: string }> | undefined {
+  const contentType = useTypedSelector((state: any) => state.contentType.value);
+  const encodingSelection = useTypedSelector(
+    (state: any) => state.encodingSelection
+  );
+
+  const specEncoding: Record<string, { contentType?: string }> =
+    requestBody?.content?.[contentType]?.encoding ?? {};
+
+  if (!Object.keys(specEncoding).length) {
+    return undefined;
+  }
+
+  return Object.fromEntries(
+    Object.entries(specEncoding).map(([field, enc]) => [
+      field,
+      {
+        ...enc,
+        contentType: encodingSelection[field] ?? enc.contentType,
+      },
+    ])
+  );
+}

package/src/theme/ApiExplorer/FormItem/_FormItem.scss

@@ -14,8 +14,3 @@
 .openapi-explorer__form-item-body-container {
   padding: 0;
 }
-
-.openapi-explorer__form-item-label {
-  font-family: var(--ifm-font-family-monospace);
-  font-weight: bold;
-}

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

@@ -7,31 +7,17 @@
 
 import React from "react";
 
-import { translate } from "@docusaurus/Translate";
-import { OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
 import clsx from "clsx";
 
 export interface Props {
-  label?: string;
-  type?: string;
-  required?: boolean | undefined;
   children?: React.ReactNode;
   className?: string;
 }
 
-function FormItem({ label, type, required, children, className }: Props) {
+function FormItem({ children, className }: Props) {
   return (
     <div className={clsx("openapi-explorer__form-item", className)}>
-      {label && (
-        <label className="openapi-explorer__form-item-label">{label}</label>
-      )}
-      {type && <span style={{ opacity: 0.6 }}> — {type}</span>}
-      {required && (
-        <span className="openapi-schema__required">
-          {translate({ id: OPENAPI_SCHEMA_ITEM.REQUIRED, message: "required" })}
-        </span>
-      )}
-      <div>{children}</div>
+      {children}
     </div>
   );
 }

package/src/theme/ApiExplorer/FormLabel/_FormLabel.scss

@@ -0,0 +1,4 @@
+.openapi-explorer__form-item-label {
+  font-family: var(--ifm-font-family-monospace);
+  font-weight: bold;
+}

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

@@ -0,0 +1,43 @@
+/* ============================================================================
+ * 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 React from "react";
+
+import { translate } from "@docusaurus/Translate";
+import { OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
+
+export interface Props {
+  htmlFor?: string;
+  label: string;
+  type?: string;
+  required?: boolean;
+}
+
+function FormLabel({ htmlFor, label, type, required }: Props) {
+  return (
+    <>
+      {htmlFor ? (
+        <label className="openapi-explorer__form-item-label" htmlFor={htmlFor}>
+          {label}
+        </label>
+      ) : (
+        <span className="openapi-explorer__form-item-label">{label}</span>
+      )}
+      {type && <span style={{ opacity: 0.6 }}> — {type}</span>}
+      {required && (
+        <span className="openapi-schema__required">
+          {translate({
+            id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+            message: "required",
+          })}
+        </span>
+      )}
+    </>
+  );
+}
+
+export default FormLabel;

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

@@ -5,8 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import React from "react";
+import React, { useId } from "react";
 
+import FormLabel from "@theme/ApiExplorer/FormLabel";
 import clsx from "clsx";
 
 export interface Props {
@@ -14,9 +15,22 @@ export interface Props {
   options: string[];
   onChange?: React.ChangeEventHandler<HTMLSelectElement>;
   showErrors?: boolean;
+  label?: string;
+  type?: string;
+  required?: boolean;
 }
 
-function FormMultiSelect({ value, options, onChange, showErrors }: Props) {
+function FormMultiSelect({
+  value,
+  options,
+  onChange,
+  showErrors,
+  label,
+  type,
+  required,
+}: Props) {
+  const id = useId();
+
   if (options.length === 0) {
     return null;
   }
@@ -33,24 +47,30 @@ function FormMultiSelect({ value, options, onChange, showErrors }: Props) {
   }
 
   return (
-    <select
-      style={{ height: height }}
-      className={clsx("openapi-explorer__multi-select-input", {
-        error: showErrors,
-      })}
-      value={value}
-      onChange={onChange}
-      size={Math.min(6, options.length + 1)}
-      multiple
-    >
-      {options.map((option) => {
-        return (
-          <option key={option} value={option}>
-            {option}
-          </option>
-        );
-      })}
-    </select>
+    <>
+      {label && (
+        <FormLabel htmlFor={id} label={label} type={type} required={required} />
+      )}
+      <select
+        id={label ? id : undefined}
+        style={{ height: height }}
+        className={clsx("openapi-explorer__multi-select-input", {
+          error: showErrors,
+        })}
+        value={value}
+        onChange={onChange}
+        size={Math.min(6, options.length + 1)}
+        multiple
+      >
+        {options.map((option) => {
+          return (
+            <option key={option} value={option}>
+              {option}
+            </option>
+          );
+        })}
+      </select>
+    </>
   );
 }
 

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

@@ -5,33 +5,59 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import React from "react";
+import React, { useId } from "react";
+
+import FormLabel from "@theme/ApiExplorer/FormLabel";
 
 export interface Props {
   value?: string;
   options?: string[];
   onChange?: React.ChangeEventHandler<HTMLSelectElement>;
+  label?: string;
+  type?: string;
+  required?: boolean;
+  ariaLabelledBy?: string;
+  ariaLabel?: string;
 }
 
-function FormSelect({ value, options, onChange }: Props) {
+function FormSelect({
+  value,
+  options,
+  onChange,
+  label,
+  type,
+  required,
+  ariaLabelledBy,
+  ariaLabel,
+}: Props) {
+  const id = useId();
+
   if (!Array.isArray(options) || options.length === 0) {
     return null;
   }
 
   return (
-    <select
-      className="openapi-explorer__select-input"
-      value={value}
-      onChange={onChange}
-    >
-      {options.map((option) => {
-        return (
-          <option key={option} value={option}>
-            {option}
-          </option>
-        );
-      })}
-    </select>
+    <>
+      {label && (
+        <FormLabel htmlFor={id} label={label} type={type} required={required} />
+      )}
+      <select
+        id={label ? id : undefined}
+        className="openapi-explorer__select-input"
+        value={value}
+        onChange={onChange}
+        aria-labelledby={!label ? ariaLabelledBy : undefined}
+        aria-label={!label && !ariaLabelledBy ? ariaLabel : undefined}
+      >
+        {options.map((option) => {
+          return (
+            <option key={option} value={option}>
+              {option}
+            </option>
+          );
+        })}
+      </select>
+    </>
   );
 }
 

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

@@ -6,10 +6,11 @@
  * ========================================================================== */
 
 // @ts-nocheck
-import React from "react";
+import React, { useId } from "react";
 
 import { translate } from "@docusaurus/Translate";
 import { ErrorMessage } from "@hookform/error-message";
+import FormLabel from "@theme/ApiExplorer/FormLabel";
 import { OPENAPI_FORM } from "@theme/translationIds";
 import clsx from "clsx";
 import { useFormContext } from "react-hook-form";
@@ -21,6 +22,9 @@ export interface Props {
   onChange?: React.ChangeEventHandler<HTMLInputElement>;
   paramName?: string;
   isRequired?: boolean;
+  label?: string;
+  type?: string;
+  required?: boolean;
 }
 
 function FormTextInput({
@@ -30,7 +34,12 @@ function FormTextInput({
   password,
   onChange,
   paramName,
+  label,
+  type,
+  required,
 }: Props) {
+  const id = useId();
+
   placeholder = placeholder?.split("\n")[0];
 
   const {
@@ -42,6 +51,9 @@ function FormTextInput({
 
   return (
     <>
+      {label && (
+        <FormLabel htmlFor={id} label={label} type={type} required={required} />
+      )}
       {paramName ? (
         <input
           {...register(paramName, {
@@ -52,6 +64,7 @@ function FormTextInput({
                 })
               : false,
           })}
+          id={label ? id : undefined}
           className={clsx("openapi-explorer__form-item-input", {
             error: showErrorMessage,
           })}
@@ -64,6 +77,7 @@ function FormTextInput({
         />
       ) : (
         <input
+          id={label ? id : undefined}
           className="openapi-explorer__form-item-input"
           type={password ? "password" : "text"}
           placeholder={placeholder}