docusaurus-theme-openapi-docs 4.7.0 → 5.0.0

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

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 
-import React, { useState } from "react";
+import React, { useState, useId } from "react";
 
 import { translate } from "@docusaurus/Translate";
 import FormItem from "@theme/ApiExplorer/FormItem";
@@ -19,36 +19,117 @@ import { OPENAPI_PARAM_OPTIONS } from "@theme/translationIds";
 
 import { Param } from "./slice";
 
+export interface LabelProps {
+  label?: string;
+  type?: string;
+  required?: boolean;
+}
+
 export interface ParamProps {
   param: Param;
 }
 
-function ParamOption({ param }: ParamProps) {
-  if (param.schema?.type === "array" && param.schema.items?.enum) {
-    return <ParamMultiSelectFormItem param={param} />;
+/**
+ * Extracts enum values from a schema, including when wrapped in allOf.
+ * This handles cases where an enum is referenced via allOf for composition.
+ */
+export function getSchemaEnum(schema: any): any[] | undefined {
+  // Direct enum on schema
+  if (schema?.enum) {
+    return schema.enum;
+  }
+
+  // Enum inside allOf - check each item
+  if (schema?.allOf && Array.isArray(schema.allOf)) {
+    for (const item of schema.allOf) {
+      if (item.enum) {
+        return item.enum;
+      }
+    }
+  }
+
+  // const is semantically a single-value enum
+  if (schema?.const !== undefined) {
+    return [schema.const];
+  }
+
+  return undefined;
+}
+
+function ParamOption({
+  param,
+  label,
+  type,
+  required,
+}: ParamProps & LabelProps) {
+  const schemaEnum = getSchemaEnum(param.schema);
+  const itemsEnum = getSchemaEnum(param.schema?.items);
+
+  if (param.schema?.type === "array" && itemsEnum) {
+    return (
+      <ParamMultiSelectFormItem
+        param={param}
+        label={label}
+        type={type}
+        required={required}
+      />
+    );
   }
 
   if (param.schema?.type === "array") {
-    return <ParamArrayFormItem param={param} />;
+    return (
+      <ParamArrayFormItem
+        param={param}
+        label={label}
+        type={type}
+        required={required}
+      />
+    );
   }
 
-  if (param.schema?.enum) {
-    return <ParamSelectFormItem param={param} />;
+  if (schemaEnum) {
+    return (
+      <ParamSelectFormItem
+        param={param}
+        label={label}
+        type={type}
+        required={required}
+      />
+    );
   }
 
   if (param.schema?.type === "boolean") {
-    return <ParamBooleanFormItem param={param} />;
+    return (
+      <ParamBooleanFormItem
+        param={param}
+        label={label}
+        type={type}
+        required={required}
+      />
+    );
   }
 
   // integer, number, string, int32, int64, float, double, object, byte, binary,
   // date-time, date, password
-  return <ParamTextFormItem param={param} />;
+  return (
+    <ParamTextFormItem
+      param={param}
+      label={label}
+      type={type}
+      required={required}
+    />
+  );
 }
 
 function ParamOptionWrapper({ param }: ParamProps) {
   return (
-    <FormItem label={param.name} type={param.in} required={param.required}>
-      <ParamOption param={param} />
+    <FormItem>
+      <ParamOption
+        param={param}
+        label={param.name}
+        type={param.in}
+        required={param.required}
+      />
     </FormItem>
   );
 }
@@ -56,6 +137,8 @@ function ParamOptionWrapper({ param }: ParamProps) {
 function ParamOptions() {
   const [showOptional, setShowOptional] = useState(false);
 
+  const optionalId = useId();
+
   const pathParams = useTypedSelector((state: any) => state.params.path);
   const queryParams = useTypedSelector((state: any) => state.params.query);
   const cookieParams = useTypedSelector((state: any) => state.params.cookie);
@@ -84,6 +167,8 @@ function ParamOptions() {
           <button
             type="button"
             className="openapi-explorer__show-more-btn"
+            aria-expanded={showOptional}
+            aria-controls={optionalId}
             onClick={() => setShowOptional((prev) => !prev)}
           >
             <span
@@ -137,6 +222,7 @@ function ParamOptions() {
                 ? "openapi-explorer__show-options"
                 : "openapi-explorer__hide-options"
             }
+            id={optionalId}
           >
             {optionalParams.map((param) => (
               <ParamOptionWrapper

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

@@ -6,7 +6,7 @@
  * ========================================================================== */
 
 import { createSlice, PayloadAction } from "@reduxjs/toolkit";
-import { ParameterObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import type { ParameterObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
 
 export type Param = ParameterObject & { value?: string[] | string };
 

package/src/theme/ApiExplorer/Request/_Request.scss

@@ -48,6 +48,17 @@
 }
 
 .openapi-explorer__expand-details-btn {
+  -webkit-appearance: none;
+  -moz-appearance: none;
+  appearance: none;
+  padding: 0;
+  cursor: pointer;
+  border: 0px solid transparent;
+  background-color: transparent;
+  text-transform: inherit;
+  font-weight: inherit;
+  font-size: inherit;
+
   &:hover {
     cursor: pointer;
   }

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

@@ -6,7 +6,7 @@
  * ========================================================================== */
 
 // @ts-nocheck
-import React, { useState } from "react";
+import React, { useState, useId } from "react";
 
 import { useDoc } from "@docusaurus/plugin-content-docs/client";
 import { translate } from "@docusaurus/Translate";
@@ -25,10 +25,11 @@ import {
   clearHeaders,
 } from "@theme/ApiExplorer/Response/slice";
 import Server from "@theme/ApiExplorer/Server";
+import { useResolvedEncoding } from "@theme/ApiExplorer/EncodingSelection/useResolvedEncoding";
 import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
 import { OPENAPI_REQUEST } from "@theme/translationIds";
-import { ParameterObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
-import { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
+import type { ParameterObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import type { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
 import type { ThemeConfig } from "docusaurus-theme-openapi-docs/src/types";
 import * as sdk from "postman-collection";
 import { FormProvider, useForm } from "react-hook-form";
@@ -43,6 +44,7 @@ function Request({ item }: { item: ApiItem }) {
   const { siteConfig } = useDocusaurusContext();
   const themeConfig = siteConfig.themeConfig as ThemeConfig;
   const requestTimeout = themeConfig.api?.requestTimeout;
+  const requestCredentials = themeConfig.api?.requestCredentials;
   // Frontmatter proxy (per-spec) takes precedence over theme config proxy (site-wide)
   const proxy = frontMatterProxy ?? themeConfig.api?.proxy;
 
@@ -66,6 +68,8 @@ function Request({ item }: { item: ApiItem }) {
   const [expandParams, setExpandParams] = useState(true);
   const [expandServer, setExpandServer] = useState(true);
 
+  const serverLabelId = useId();
+
   const allParams = [
     ...pathParams,
     ...queryParams,
@@ -73,6 +77,8 @@ function Request({ item }: { item: ApiItem }) {
     ...headerParams,
   ];
 
+  const encoding = useResolvedEncoding(item.requestBody);
+
   const postmanRequest = buildPostmanRequest(postman, {
     queryParams,
     pathParams,
@@ -83,6 +89,7 @@ function Request({ item }: { item: ApiItem }) {
     body,
     server,
     auth,
+    encoding,
   });
 
   const delay = (ms: number) =>
@@ -99,7 +106,7 @@ function Request({ item }: { item: ApiItem }) {
     (param: { in: "path" | "query" | "header" | "cookie" }) => {
       const paramType = param.in;
       const paramsArray: ParameterObject[] = paramsObject[paramType];
-      paramsArray.push(param as ParameterObject);
+      paramsArray?.push(param as ParameterObject);
     }
   );
 
@@ -171,7 +178,9 @@ function Request({ item }: { item: ApiItem }) {
         postmanRequest,
         proxy,
         body,
-        requestTimeout
+        requestTimeout,
+        requestCredentials,
+        encoding
       );
       if (res.headers.get("content-type")?.includes("text/event-stream")) {
         await handleEventStream(res);
@@ -249,7 +258,8 @@ function Request({ item }: { item: ApiItem }) {
             })}
           </span>
           {allDetailsExpanded ? (
-            <span
+            <button
+              type="button"
               className="openapi-explorer__expand-details-btn"
               onClick={collapseAllDetails}
             >
@@ -257,9 +267,10 @@ function Request({ item }: { item: ApiItem }) {
                 id: OPENAPI_REQUEST.COLLAPSE_ALL,
                 message: "Collapse all",
               })}
-            </span>
+            </button>
           ) : (
-            <span
+            <button
+              type="button"
               className="openapi-explorer__expand-details-btn"
               onClick={expandAllDetails}
             >
@@ -267,7 +278,7 @@ function Request({ item }: { item: ApiItem }) {
                 id: OPENAPI_REQUEST.EXPAND_ALL,
                 message: "Expand all",
               })}
-            </span>
+            </button>
           )}
         </div>
         <div className="openapi-explorer__details-outer-container">
@@ -277,6 +288,7 @@ function Request({ item }: { item: ApiItem }) {
               className="openapi-explorer__details-container"
             >
               <summary
+                id={serverLabelId}
                 className="openapi-explorer__details-summary"
                 onClick={(e) => {
                   e.preventDefault();
@@ -288,7 +300,7 @@ function Request({ item }: { item: ApiItem }) {
                   message: "Base URL",
                 })}
               </summary>
-              <Server />
+              <Server labelId={serverLabelId} />
             </details>
           )}
           {showAuth && (

package/src/theme/ApiExplorer/Request/makeRequest.ts

@@ -114,7 +114,9 @@ async function makeRequest(
   request: sdk.Request,
   proxy: string | undefined,
   _body: Body,
-  timeout: number = DEFAULT_REQUEST_TIMEOUT
+  timeout: number = DEFAULT_REQUEST_TIMEOUT,
+  credentials?: RequestCredentials,
+  encoding?: Record<string, { contentType?: string }>
 ) {
   const headers = request.toJSON().header;
 
@@ -226,12 +228,25 @@ async function makeRequest(
         const members = (request.body as any)?.formdata?.members;
         if (Array.isArray(members)) {
           for (const data of members) {
+            const partContentType = encoding?.[data.key]?.contentType
+              ?.split(",")[0]
+              .trim();
             if (data.key && data.value.content) {
-              myBody.append(data.key, data.value.content);
+              const blob = partContentType
+                ? new Blob([data.value.content], { type: partContentType })
+                : data.value.content;
+              myBody.append(data.key, blob);
             }
             // handle generic key-value payload
             if (data.key && typeof data.value === "string") {
-              myBody.append(data.key, data.value);
+              if (partContentType) {
+                myBody.append(
+                  data.key,
+                  new Blob([data.value], { type: partContentType })
+                );
+              } else {
+                myBody.append(data.key, data.value);
+              }
             }
           }
         }
@@ -252,6 +267,7 @@ async function makeRequest(
     method: request.method,
     headers: myHeaders,
     body: myBody,
+    ...(credentials && { credentials }),
   };
 
   let finalUrl = request.url.toString();

package/src/theme/ApiExplorer/Response/_Response.scss

@@ -43,6 +43,17 @@
 }
 
 .openapi-explorer__response-clear-btn {
+  -webkit-appearance: none;
+  -moz-appearance: none;
+  appearance: none;
+  padding: 0;
+  cursor: pointer;
+  border: 0px solid transparent;
+  background-color: transparent;
+  text-transform: inherit;
+  font-weight: inherit;
+  font-size: inherit;
+
   &:hover {
     cursor: pointer;
   }

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

@@ -9,15 +9,15 @@ import React from "react";
 
 import { useDoc } from "@docusaurus/plugin-content-docs/client";
 import { usePrismTheme } from "@docusaurus/theme-common";
-import { translate } from "@docusaurus/Translate";
+import Translate, { translate } from "@docusaurus/Translate";
 import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
 import ApiCodeBlock from "@theme/ApiExplorer/ApiCodeBlock";
 import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
 import SchemaTabs from "@theme/SchemaTabs";
 import TabItem from "@theme/TabItem";
-import { OPENAPI_RESPONSE } from "@theme/translationIds";
+import { OPENAPI_REQUEST, OPENAPI_RESPONSE } from "@theme/translationIds";
 import clsx from "clsx";
-import { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
+import type { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
 import type { ThemeConfig } from "docusaurus-theme-openapi-docs/src/types";
 
 import { clearResponse, clearCode, clearHeaders } from "./slice";
@@ -47,8 +47,7 @@ function Response({ item }: { item: ApiItem }) {
   const { siteConfig } = useDocusaurusContext();
   const themeConfig = siteConfig.themeConfig as ThemeConfig;
   const hideSendButton = metadata.frontMatter.hide_send_button;
-  const proxy =
-    metadata.frontMatter.proxy ?? themeConfig.api?.proxy;
+  const proxy = metadata.frontMatter.proxy ?? themeConfig.api?.proxy;
   const prismTheme = usePrismTheme();
   const code = useTypedSelector((state: any) => state.response.code);
   const headers = useTypedSelector((state: any) => state.response.headers);
@@ -85,7 +84,8 @@ function Response({ item }: { item: ApiItem }) {
         <span className="openapi-explorer__response-title">
           {translate({ id: OPENAPI_RESPONSE.TITLE, message: "Response" })}
         </span>
-        <span
+        <button
+          type="button"
           className="openapi-explorer__response-clear-btn"
           onClick={() => {
             dispatch(clearResponse());
@@ -94,7 +94,7 @@ function Response({ item }: { item: ApiItem }) {
           }}
         >
           {translate({ id: OPENAPI_RESPONSE.CLEAR, message: "Clear" })}
-        </span>
+        </button>
       </div>
       <div
         style={{
@@ -127,11 +127,22 @@ function Response({ item }: { item: ApiItem }) {
               >
                 {prettyResponse || (
                   <p className="openapi-explorer__response-placeholder-message">
-                    {translate({
-                      id: OPENAPI_RESPONSE.PLACEHOLDER,
-                      message:
-                        "Click the <code>Send API Request</code> button above and see the response here!",
-                    })}
+                    <Translate
+                      id={OPENAPI_RESPONSE.PLACEHOLDER}
+                      values={{
+                        code: (
+                          <code>
+                            <Translate id={OPENAPI_REQUEST.SEND_BUTTON}>
+                              Send API Request
+                            </Translate>
+                          </code>
+                        ),
+                      }}
+                    >
+                      {
+                        "Click the {code} button above and see the response here!"
+                      }
+                    </Translate>
                   </p>
                 )}
               </ApiCodeBlock>
@@ -164,11 +175,20 @@ function Response({ item }: { item: ApiItem }) {
           </div>
         ) : (
           <p className="openapi-explorer__response-placeholder-message">
-            {translate({
-              id: OPENAPI_RESPONSE.PLACEHOLDER,
-              message:
-                "Click the <code>Send API Request</code> button above and see the response here!",
-            })}
+            <Translate
+              id={OPENAPI_RESPONSE.PLACEHOLDER}
+              values={{
+                code: (
+                  <code>
+                    <Translate id={OPENAPI_REQUEST.SEND_BUTTON}>
+                      Send API Request
+                    </Translate>
+                  </code>
+                ),
+              }}
+            >
+              {"Click the {code} button above and see the response here!"}
+            </Translate>
           </p>
         )}
       </div>

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

@@ -7,11 +7,10 @@
 
 import React from "react";
 
-import { translate } from "@docusaurus/Translate";
-import { OPENAPI_SECURITY_SCHEMES } from "@theme/translationIds";
-
 import Link from "@docusaurus/Link";
+import { translate } from "@docusaurus/Translate";
 import { useTypedSelector } from "@theme/ApiItem/hooks";
+import { OPENAPI_SECURITY_SCHEMES } from "@theme/translationIds";
 
 function SecuritySchemes(props: any) {
   const options = useTypedSelector((state: any) => state.auth.options);

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

@@ -17,7 +17,11 @@ import { OPENAPI_SERVER } from "@theme/translationIds";
 
 import { setServer, setServerVariable } from "./slice";
 
-function Server() {
+interface ServerProps {
+  labelId?: string;
+}
+
+function Server({ labelId }: ServerProps) {
   const [isEditing, setIsEditing] = useState(false);
   const value = useTypedSelector((state: any) => state.server.value);
   const options = useTypedSelector((state: any) => state.server.options);
@@ -79,6 +83,7 @@ function Server() {
       >
         <FormItem>
           <FormSelect
+            ariaLabelledBy={labelId}
             options={options.map((s: any) => s.url)}
             onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
               dispatch(
@@ -99,8 +104,9 @@ function Server() {
           Object.keys(value.variables).map((key) => {
             if (value.variables?.[key].enum !== undefined) {
               return (
-                <FormItem label={key}>
+                <FormItem>
                   <FormSelect
+                    label={key}
                     options={value.variables[key].enum}
                     onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
                       dispatch(
@@ -115,8 +121,9 @@ function Server() {
               );
             }
             return (
-              <FormItem label={key}>
+              <FormItem>
                 <FormTextInput
+                  label={key}
                   placeholder={value.variables?.[key].default}
                   onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
                     dispatch(

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

@@ -6,7 +6,7 @@
  * ========================================================================== */
 
 import { createSlice, PayloadAction } from "@reduxjs/toolkit";
-import { ServerObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import type { ServerObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
 // TODO: we might want to export this
 
 export interface State {

package/src/theme/ApiExplorer/buildPostmanRequest.ts

@@ -7,7 +7,7 @@
 
 import { AuthState, Scheme } from "@theme/ApiExplorer/Authorization/slice";
 import { Body, Content } from "@theme/ApiExplorer/Body/slice";
-import {
+import type {
   ParameterObject,
   ServerObject,
 } from "docusaurus-plugin-openapi-docs/src/openapi/types";
@@ -293,12 +293,36 @@ function tryDecodeJsonParam(value: string): any {
 }
 
 // TODO: this is all a bit hacky
-function setBody(clonedPostman: sdk.Request, body: Body) {
+function setBody(
+  clonedPostman: sdk.Request,
+  body: Body,
+  encoding?: Record<string, { contentType?: string }>
+) {
   if (clonedPostman.body === undefined) {
     return;
   }
 
   if (body.type === "empty") {
+    // When the original request has formdata and encoding is declared, keep the
+    // placeholder params so the code snippet reflects the selected encoding even
+    // before the user has uploaded a file.
+    if (
+      clonedPostman.body?.mode === "formdata" &&
+      encoding &&
+      Object.keys(encoding).length > 0
+    ) {
+      const members: any[] =
+        (clonedPostman.body.formdata as any)?.members ?? [];
+      members.forEach((param: any) => {
+        const partContentType = encoding[param.key]?.contentType
+          ?.split(",")[0]
+          .trim();
+        if (partContentType) {
+          param.contentType = partContentType;
+        }
+      });
+      return;
+    }
     clonedPostman.body = undefined;
     return;
   }
@@ -336,14 +360,35 @@ function setBody(clonedPostman: sdk.Request, body: Body) {
       Object.entries(body.content)
         .filter((entry): entry is [string, NonNullable<Content>] => !!entry[1])
         .forEach(([key, content]) => {
+          const partContentType = encoding?.[key]?.contentType
+            ?.split(",")[0]
+            .trim();
           if (content.type === "file") {
-            params.push(new sdk.FormParam({ key: key, ...content }));
+            params.push(
+              new sdk.FormParam({
+                key: key,
+                ...content,
+                ...(partContentType && { contentType: partContentType }),
+              })
+            );
           } else if (content.type === "file[]") {
             content.value.forEach((file) =>
-              params.push(new sdk.FormParam({ key, value: file }))
+              params.push(
+                new sdk.FormParam({
+                  key,
+                  value: file,
+                  ...(partContentType && { contentType: partContentType }),
+                })
+              )
             );
           } else {
-            params.push(new sdk.FormParam({ key: key, value: content.value }));
+            params.push(
+              new sdk.FormParam({
+                key: key,
+                value: content.value,
+                ...(partContentType && { contentType: partContentType }),
+              })
+            );
           }
         });
       params.forEach((param) => {
@@ -391,6 +436,7 @@ interface Options {
   accept: string;
   body: Body;
   auth: AuthState;
+  encoding?: Record<string, { contentType?: string }>;
 }
 
 function buildPostmanRequest(
@@ -405,6 +451,7 @@ function buildPostmanRequest(
     body,
     server,
     auth,
+    encoding,
   }: Options
 ) {
   const clonedPostman = cloneDeep(postman);
@@ -532,7 +579,7 @@ function buildPostmanRequest(
     otherHeaders
   );
 
-  setBody(clonedPostman, body);
+  setBody(clonedPostman, body, encoding);
 
   return clonedPostman;
 }

package/src/theme/ApiExplorer/index.tsx

@@ -12,7 +12,7 @@ import CodeSnippets from "@theme/ApiExplorer/CodeSnippets";
 import Request from "@theme/ApiExplorer/Request";
 import Response from "@theme/ApiExplorer/Response";
 import SecuritySchemes from "@theme/ApiExplorer/SecuritySchemes";
-import { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
+import type { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
 import * as sdk from "postman-collection";
 
 function ApiExplorer({
@@ -41,6 +41,7 @@ function ApiExplorer({
           postman={postman}
           codeSamples={(item as any)["x-codeSamples"] ?? []}
           maskCredentials={mask_credentials}
+          requestBody={item.requestBody}
         />
       )}
       <Request item={item} />