docusaurus-theme-openapi-docs 4.7.0 → 5.0.0

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,32 +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}

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

@@ -8,6 +8,7 @@
 import React from "react";
 
 import BrowserOnly from "@docusaurus/BrowserOnly";
+import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment";
 import { useTypedSelector } from "@theme/ApiItem/hooks";
 
 function colorForMethod(method: string) {
@@ -38,6 +39,26 @@ export interface Props {
 }
 
 function MethodEndpoint({ method, path, context }: Props) {
+  // During SSR, render without Redux store access to avoid "Cannot read properties
+  // of null (reading 'store')" errors caused by useSelector running outside a Provider.
+  if (!ExecutionEnvironment.canUseDOM) {
+    return (
+      <>
+        <pre className="openapi__method-endpoint">
+          <span className={"badge badge--" + colorForMethod(method)}>
+            {method === "event" ? "Webhook" : method.toUpperCase()}
+          </span>{" "}
+          {method !== "event" && (
+            <h2 className="openapi__method-endpoint-path">
+              {`${path.replace(/{([a-z0-9-_]+)}/gi, ":$1")}`}
+            </h2>
+          )}
+        </pre>
+        <div className="openapi__divider" />
+      </>
+    );
+  }
+
   let serverValue = useTypedSelector((state: any) => state.server.value);
   let serverUrlWithVariables = "";
 

package/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamArrayFormItem.tsx

@@ -10,6 +10,7 @@ import React, { useEffect, useState } from "react";
 import { translate } from "@docusaurus/Translate";
 import { ErrorMessage } from "@hookform/error-message";
 import { nanoid } from "@reduxjs/toolkit";
+import FormLabel from "@theme/ApiExplorer/FormLabel";
 import FormSelect from "@theme/ApiExplorer/FormSelect";
 import FormTextInput from "@theme/ApiExplorer/FormTextInput";
 import { Param, setParam } from "@theme/ApiExplorer/ParamOptions/slice";
@@ -19,6 +20,9 @@ import { Controller, useFormContext } from "react-hook-form";
 
 export interface ParamProps {
   param: Param;
+  label?: string;
+  type?: string;
+  required?: boolean;
 }
 
 function ArrayItem({
@@ -31,6 +35,7 @@ function ArrayItem({
   if (param.schema?.items?.type === "boolean") {
     return (
       <FormSelect
+        ariaLabel={param.description || param.name}
         options={["---", "true", "false"]}
         onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
           const val = e.target.value;
@@ -52,7 +57,12 @@ function ArrayItem({
   );
 }
 
-export default function ParamArrayFormItem({ param }: ParamProps) {
+export default function ParamArrayFormItem({
+  param,
+  label,
+  type,
+  required,
+}: ParamProps) {
   const [items, setItems] = useState<{ id: string; value?: string }[]>([]);
   const dispatch = useTypedDispatch();
 
@@ -122,6 +132,7 @@ export default function ParamArrayFormItem({ param }: ParamProps) {
 
   return (
     <>
+      {label && <FormLabel label={label} type={type} required={required} />}
       <Controller
         control={control}
         rules={{
@@ -145,6 +156,7 @@ export default function ParamArrayFormItem({ param }: ParamProps) {
                 <button
                   className="openapi-explorer__delete-btn"
                   onClick={handleDeleteItem(item)}
+                  aria-label="Delete"
                 >
                   <svg
                     focusable="false"
@@ -157,7 +169,6 @@ export default function ParamArrayFormItem({ param }: ParamProps) {
                     aria-hidden="true"
                   >
                     <path d="M24 9.4L22.6 8 16 14.6 9.4 8 8 9.4 14.6 16 8 22.6 9.4 24 16 17.4 22.6 24 24 22.6 17.4 16 24 9.4z"></path>
-                    <title>Delete</title>
                   </svg>
                 </button>
               </div>

package/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamBooleanFormItem.tsx

@@ -17,9 +17,17 @@ import { Controller, useFormContext } from "react-hook-form";
 
 export interface ParamProps {
   param: Param;
+  label?: string;
+  type?: string;
+  required?: boolean;
 }
 
-export default function ParamBooleanFormItem({ param }: ParamProps) {
+export default function ParamBooleanFormItem({
+  param,
+  label,
+  type,
+  required,
+}: ParamProps) {
   const dispatch = useTypedDispatch();
 
   const {
@@ -44,6 +52,9 @@ export default function ParamBooleanFormItem({ param }: ParamProps) {
         name="paramBoolean"
         render={({ field: { onChange } }) => (
           <FormSelect
+            label={label}
+            type={type}
+            required={required}
             options={["---", "true", "false"]}
             onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
               const val = e.target.value;

package/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamMultiSelectFormItem.tsx

@@ -10,6 +10,7 @@ import React from "react";
 import { translate } from "@docusaurus/Translate";
 import { ErrorMessage } from "@hookform/error-message";
 import FormMultiSelect from "@theme/ApiExplorer/FormMultiSelect";
+import { getSchemaEnum } from "@theme/ApiExplorer/ParamOptions";
 import { Param, setParam } from "@theme/ApiExplorer/ParamOptions/slice";
 import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
 import { OPENAPI_FORM } from "@theme/translationIds";
@@ -17,9 +18,17 @@ import { Controller, useFormContext } from "react-hook-form";
 
 export interface ParamProps {
   param: Param;
+  label?: string;
+  type?: string;
+  required?: boolean;
 }
 
-export default function ParamMultiSelectFormItem({ param }: ParamProps) {
+export default function ParamMultiSelectFormItem({
+  param,
+  label,
+  type,
+  required,
+}: ParamProps) {
   const {
     control,
     formState: { errors },
@@ -29,7 +38,7 @@ export default function ParamMultiSelectFormItem({ param }: ParamProps) {
 
   const dispatch = useTypedDispatch();
 
-  const options = param.schema?.items?.enum ?? [];
+  const options = getSchemaEnum(param.schema?.items) ?? [];
 
   const pathParams = useTypedSelector((state: any) => state.params.path);
   const queryParams = useTypedSelector((state: any) => state.params.query);
@@ -74,6 +83,9 @@ export default function ParamMultiSelectFormItem({ param }: ParamProps) {
         name="paramMultiSelect"
         render={({ field: { onChange } }) => (
           <FormMultiSelect
+            label={label}
+            type={type}
+            required={required}
             options={options as string[]}
             onChange={(e: any) => handleChange(e, onChange)}
             showErrors={!!showErrorMessage}

package/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamSelectFormItem.tsx

@@ -10,6 +10,7 @@ import React from "react";
 import { translate } from "@docusaurus/Translate";
 import { ErrorMessage } from "@hookform/error-message";
 import FormSelect from "@theme/ApiExplorer/FormSelect";
+import { getSchemaEnum } from "@theme/ApiExplorer/ParamOptions";
 import { Param, setParam } from "@theme/ApiExplorer/ParamOptions/slice";
 import { useTypedDispatch } from "@theme/ApiItem/hooks";
 import { OPENAPI_FORM } from "@theme/translationIds";
@@ -17,9 +18,17 @@ import { Controller, useFormContext } from "react-hook-form";
 
 export interface ParamProps {
   param: Param;
+  label?: string;
+  type?: string;
+  required?: boolean;
 }
 
-export default function ParamSelectFormItem({ param }: ParamProps) {
+export default function ParamSelectFormItem({
+  param,
+  label,
+  type,
+  required,
+}: ParamProps) {
   const {
     control,
     formState: { errors },
@@ -29,7 +38,7 @@ export default function ParamSelectFormItem({ param }: ParamProps) {
 
   const dispatch = useTypedDispatch();
 
-  const options = param.schema?.enum ?? [];
+  const options = getSchemaEnum(param.schema) ?? [];
 
   return (
     <>
@@ -46,6 +55,9 @@ export default function ParamSelectFormItem({ param }: ParamProps) {
         name="paramSelect"
         render={({ field: { onChange } }) => (
           <FormSelect
+            label={label}
+            type={type}
+            required={required}
             options={["---", ...(options as string[])]}
             onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
               const val = e.target.value;

package/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamTextFormItem.tsx

@@ -13,12 +13,23 @@ import { useTypedDispatch } from "@theme/ApiItem/hooks";
 
 export interface ParamProps {
   param: Param;
+  label?: string;
+  type?: string;
+  required?: boolean;
 }
 
-export default function ParamTextFormItem({ param }: ParamProps) {
+export default function ParamTextFormItem({
+  param,
+  label,
+  type,
+  required,
+}: ParamProps) {
   const dispatch = useTypedDispatch();
   return (
     <FormTextInput
+      label={label}
+      type={type}
+      required={required}
       isRequired={param.required}
       paramName={param.name}
       placeholder={param.description || param.name}
@@ -27,9 +38,11 @@ export default function ParamTextFormItem({ param }: ParamProps) {
           setParam({
             ...param,
             value:
-              param.in === "path" || param.in === "query"
+              param.in === "path"
                 ? e.target.value.replace(/\s/g, "%20")
-                : e.target.value,
+                : param.in === "query"
+                  ? encodeURIComponent(e.target.value)
+                  : e.target.value,
           })
         )
       }

package/src/theme/ApiExplorer/ParamOptions/_ParamOptions.scss

@@ -63,15 +63,10 @@
   margin-top: calc(var(--ifm-pre-padding) / 2);
   background-color: var(--openapi-input-background);
   border: none;
-  outline: none;
   color: var(--ifm-pre-color);
   border-radius: 4px;
   margin-left: 4px;
 
-  &:focus {
-    outline: 0;
-  }
-
   &:active {
     box-shadow: inset 0px 0px 0px 2px var(--openapi-input-border);
   }
@@ -102,10 +97,6 @@
     background-color: var(--openapi-input-border);
   }
 
-  &:focus {
-    outline: 0;
-  }
-
   &:active {
     box-shadow:
       inset 0 0 0 1px var(--openapi-input-border),