docusaurus-theme-openapi-docs 4.5.1 → 4.7.0

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

@@ -7,10 +7,12 @@
 
 import React from "react";
 
+import { translate } from "@docusaurus/Translate";
 import { ErrorMessage } from "@hookform/error-message";
 import FormSelect from "@theme/ApiExplorer/FormSelect";
 import { Param, setParam } from "@theme/ApiExplorer/ParamOptions/slice";
 import { useTypedDispatch } from "@theme/ApiItem/hooks";
+import { OPENAPI_FORM } from "@theme/translationIds";
 import { Controller, useFormContext } from "react-hook-form";
 
 export interface ParamProps {
@@ -33,12 +35,19 @@ export default function ParamSelectFormItem({ param }: ParamProps) {
     <>
       <Controller
         control={control}
-        rules={{ required: param.required ? "This field is required" : false }}
+        rules={{
+          required: param.required
+            ? translate({
+                id: OPENAPI_FORM.FIELD_REQUIRED,
+                message: "This field is required",
+              })
+            : false,
+        }}
         name="paramSelect"
-        render={({ field: { onChange, name } }) => (
+        render={({ field: { onChange } }) => (
           <FormSelect
             options={["---", ...(options as string[])]}
-            onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
+            onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
               const val = e.target.value;
               dispatch(
                 setParam({

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

@@ -7,6 +7,7 @@
 
 import React, { useState } from "react";
 
+import { translate } from "@docusaurus/Translate";
 import FormItem from "@theme/ApiExplorer/FormItem";
 import ParamArrayFormItem from "@theme/ApiExplorer/ParamOptions/ParamFormItems/ParamArrayFormItem";
 import ParamBooleanFormItem from "@theme/ApiExplorer/ParamOptions/ParamFormItems/ParamBooleanFormItem";
@@ -14,6 +15,7 @@ import ParamMultiSelectFormItem from "@theme/ApiExplorer/ParamOptions/ParamFormI
 import ParamSelectFormItem from "@theme/ApiExplorer/ParamOptions/ParamFormItems/ParamSelectFormItem";
 import ParamTextFormItem from "@theme/ApiExplorer/ParamOptions/ParamFormItems/ParamTextFormItem";
 import { useTypedSelector } from "@theme/ApiItem/hooks";
+import { OPENAPI_PARAM_OPTIONS } from "@theme/translationIds";
 
 import { Param } from "./slice";
 
@@ -119,8 +121,14 @@ function ParamOptions() {
               </span>
             </span>
             {showOptional
-              ? "Hide optional parameters"
-              : "Show optional parameters"}
+              ? translate({
+                  id: OPENAPI_PARAM_OPTIONS.HIDE_OPTIONAL,
+                  message: "Hide optional parameters",
+                })
+              : translate({
+                  id: OPENAPI_PARAM_OPTIONS.SHOW_OPTIONAL,
+                  message: "Show optional parameters",
+                })}
           </button>
 
           <div

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

@@ -19,7 +19,7 @@ export interface State {
 
 const initialState: State = {} as any;
 
-export const slice = createSlice({
+const slice = createSlice({
   name: "params",
   initialState,
   reducers: {

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

@@ -9,6 +9,8 @@
 import React, { useState } from "react";
 
 import { useDoc } from "@docusaurus/plugin-content-docs/client";
+import { translate } from "@docusaurus/Translate";
+import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
 import Accept from "@theme/ApiExplorer/Accept";
 import Authorization from "@theme/ApiExplorer/Authorization";
 import Body from "@theme/ApiExplorer/Body";
@@ -24,17 +26,25 @@ import {
 } from "@theme/ApiExplorer/Response/slice";
 import Server from "@theme/ApiExplorer/Server";
 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 { ThemeConfig } from "docusaurus-theme-openapi-docs/src/types";
 import * as sdk from "postman-collection";
 import { FormProvider, useForm } from "react-hook-form";
 
-import makeRequest from "./makeRequest";
+import makeRequest, { RequestError, RequestErrorType } from "./makeRequest";
 
 function Request({ item }: { item: ApiItem }) {
   const postman = new sdk.Request(item.postman);
   const metadata = useDoc();
-  const { proxy, hide_send_button: hideSendButton } = metadata.frontMatter;
+  const { proxy: frontMatterProxy, hide_send_button: hideSendButton } =
+    metadata.frontMatter;
+  const { siteConfig } = useDocusaurusContext();
+  const themeConfig = siteConfig.themeConfig as ThemeConfig;
+  const requestTimeout = themeConfig.api?.requestTimeout;
+  // Frontmatter proxy (per-spec) takes precedence over theme config proxy (site-wide)
+  const proxy = frontMatterProxy ?? themeConfig.api?.proxy;
 
   const pathParams = useTypedSelector((state: any) => state.params.path);
   const queryParams = useTypedSelector((state: any) => state.params.query);
@@ -116,11 +126,53 @@ function Request({ item }: { item: ApiItem }) {
     res.headers && dispatch(setHeaders(Object.fromEntries(res.headers)));
   };
 
+  const getErrorMessage = (errorType: RequestErrorType): string => {
+    switch (errorType) {
+      case "timeout":
+        return translate({
+          id: OPENAPI_REQUEST.ERROR_TIMEOUT,
+          message:
+            "The request timed out waiting for the server to respond. Please try again. If the issue persists, try using a different client (e.g., curl) with a longer timeout.",
+        });
+      case "network":
+        return translate({
+          id: OPENAPI_REQUEST.ERROR_NETWORK,
+          message:
+            "Unable to reach the server. Please check your network connection and verify the server URL is correct. If the server is running, this may be a CORS issue.",
+        });
+      case "cors":
+        return translate({
+          id: OPENAPI_REQUEST.ERROR_CORS,
+          message:
+            "The request was blocked, possibly due to CORS restrictions. Ensure the server allows requests from this origin, or try using a proxy.",
+        });
+      case "unknown":
+      default:
+        return translate({
+          id: OPENAPI_REQUEST.ERROR_UNKNOWN,
+          message:
+            "An unexpected error occurred while making the request. Please try again.",
+        });
+    }
+  };
+
   const onSubmit = async (data) => {
-    dispatch(setResponse("Fetching..."));
+    dispatch(
+      setResponse(
+        translate({
+          id: OPENAPI_REQUEST.FETCHING_MESSAGE,
+          message: "Fetching...",
+        })
+      )
+    );
     try {
       await delay(1200);
-      const res = await makeRequest(postmanRequest, proxy, body);
+      const res = await makeRequest(
+        postmanRequest,
+        proxy,
+        body,
+        requestTimeout
+      );
       if (res.headers.get("content-type")?.includes("text/event-stream")) {
         await handleEventStream(res);
       } else {
@@ -128,7 +180,18 @@ function Request({ item }: { item: ApiItem }) {
       }
     } catch (e) {
       console.log(e);
-      dispatch(setResponse("Connection failed"));
+
+      let errorMessage: string;
+      if (e instanceof RequestError) {
+        errorMessage = getErrorMessage(e.type);
+      } else {
+        errorMessage = translate({
+          id: OPENAPI_REQUEST.CONNECTION_FAILED,
+          message: "Connection failed",
+        });
+      }
+
+      dispatch(setResponse(errorMessage));
       dispatch(clearCode());
       dispatch(clearHeaders());
     }
@@ -137,7 +200,7 @@ function Request({ item }: { item: ApiItem }) {
   const showServerOptions = serverOptions.length > 0;
   const showAcceptOptions = acceptOptions.length > 1;
   const showRequestBody = contentType !== undefined;
-  const showRequestButton = item.servers && !hideSendButton;
+  const showRequestButton = (item.servers || proxy) && !hideSendButton;
   const showAuth = authSelected !== undefined;
   const showParams = allParams.length > 0;
   const requestBodyRequired = item.requestBody?.required;
@@ -147,7 +210,8 @@ function Request({ item }: { item: ApiItem }) {
     !showAuth &&
     !showParams &&
     !showRequestBody &&
-    !showServerOptions
+    !showServerOptions &&
+    !showRequestButton
   ) {
     return null;
   }
@@ -178,20 +242,31 @@ function Request({ item }: { item: ApiItem }) {
         onSubmit={methods.handleSubmit(onSubmit)}
       >
         <div className="openapi-explorer__request-header-container">
-          <span className="openapi-explorer__request-title">Request </span>
+          <span className="openapi-explorer__request-title">
+            {translate({
+              id: OPENAPI_REQUEST.REQUEST_TITLE,
+              message: "Request",
+            })}
+          </span>
           {allDetailsExpanded ? (
             <span
               className="openapi-explorer__expand-details-btn"
               onClick={collapseAllDetails}
             >
-              Collapse all
+              {translate({
+                id: OPENAPI_REQUEST.COLLAPSE_ALL,
+                message: "Collapse all",
+              })}
             </span>
           ) : (
             <span
               className="openapi-explorer__expand-details-btn"
               onClick={expandAllDetails}
             >
-              Expand all
+              {translate({
+                id: OPENAPI_REQUEST.EXPAND_ALL,
+                message: "Expand all",
+              })}
             </span>
           )}
         </div>
@@ -208,7 +283,10 @@ function Request({ item }: { item: ApiItem }) {
                   setExpandServer(!expandServer);
                 }}
               >
-                Base URL
+                {translate({
+                  id: OPENAPI_REQUEST.BASE_URL_TITLE,
+                  message: "Base URL",
+                })}
               </summary>
               <Server />
             </details>
@@ -225,7 +303,7 @@ function Request({ item }: { item: ApiItem }) {
                   setExpandAuth(!expandAuth);
                 }}
               >
-                Auth
+                {translate({ id: OPENAPI_REQUEST.AUTH_TITLE, message: "Auth" })}
               </summary>
               <Authorization />
             </details>
@@ -244,7 +322,10 @@ function Request({ item }: { item: ApiItem }) {
                   setExpandParams(!expandParams);
                 }}
               >
-                Parameters
+                {translate({
+                  id: OPENAPI_REQUEST.PARAMETERS_TITLE,
+                  message: "Parameters",
+                })}
               </summary>
               <ParamOptions />
             </details>
@@ -261,10 +342,14 @@ function Request({ item }: { item: ApiItem }) {
                   setExpandBody(!expandBody);
                 }}
               >
-                Body
+                {translate({ id: OPENAPI_REQUEST.BODY_TITLE, message: "Body" })}
                 {requestBodyRequired && (
                   <span className="openapi-schema__required">
-                    &nbsp;required
+                    &nbsp;
+                    {translate({
+                      id: OPENAPI_REQUEST.REQUIRED_LABEL,
+                      message: "required",
+                    })}
                   </span>
                 )}
               </summary>
@@ -290,14 +375,20 @@ function Request({ item }: { item: ApiItem }) {
                   setExpandAccept(!expandAccept);
                 }}
               >
-                Accept
+                {translate({
+                  id: OPENAPI_REQUEST.ACCEPT_TITLE,
+                  message: "Accept",
+                })}
               </summary>
               <Accept />
             </details>
           )}
           {showRequestButton && item.method !== "event" && (
             <button className="openapi-explorer__request-btn" type="submit">
-              Send API Request
+              {translate({
+                id: OPENAPI_REQUEST.SEND_BUTTON,
+                message: "Send API Request",
+              })}
             </button>
           )}
         </div>

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

@@ -8,17 +8,83 @@
 import { Body } from "@theme/ApiExplorer/Body/slice";
 import * as sdk from "postman-collection";
 
+// Custom error types for better error handling
+export type RequestErrorType =
+  | "timeout"
+  | "network"
+  | "cors"
+  | "abort"
+  | "unknown";
+
+export class RequestError extends Error {
+  type: RequestErrorType;
+  originalError?: Error;
+
+  constructor(type: RequestErrorType, message: string, originalError?: Error) {
+    super(message);
+    this.name = "RequestError";
+    this.type = type;
+    this.originalError = originalError;
+  }
+}
+
+const DEFAULT_REQUEST_TIMEOUT = 30000; // 30 seconds
+
 function fetchWithtimeout(
   url: string,
   options: RequestInit,
-  timeout = 5000
-): any {
-  return Promise.race([
-    fetch(url, options),
-    new Promise((_, reject) =>
-      setTimeout(() => reject(new Error("Request timed out")), timeout)
-    ),
-  ]);
+  timeout = DEFAULT_REQUEST_TIMEOUT
+): Promise<Response> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+  return fetch(url, {
+    ...options,
+    signal: controller.signal,
+  })
+    .then((response) => {
+      clearTimeout(timeoutId);
+      return response;
+    })
+    .catch((error) => {
+      clearTimeout(timeoutId);
+
+      // Check if it was an abort due to timeout
+      if (error.name === "AbortError") {
+        throw new RequestError(
+          "timeout",
+          "The request timed out waiting for the server to respond. Please try again. If the issue persists, try using a different client (e.g., curl) with a longer timeout.",
+          error
+        );
+      }
+
+      // Check for network errors (offline, DNS failure, etc.)
+      if (error instanceof TypeError && error.message === "Failed to fetch") {
+        // This could be CORS, network failure, or the server being unreachable
+        throw new RequestError(
+          "network",
+          "Unable to reach the server. Please check your network connection and verify the server URL is correct. If the server is running, this may be a CORS issue.",
+          error
+        );
+      }
+
+      // Handle other TypeErrors that might indicate CORS issues
+      if (error instanceof TypeError) {
+        throw new RequestError(
+          "cors",
+          "The request was blocked, possibly due to CORS restrictions. Ensure the server allows requests from this origin, or try using a proxy.",
+          error
+        );
+      }
+
+      // Generic error fallback
+      throw new RequestError(
+        "unknown",
+        error.message ||
+          "An unexpected error occurred while making the request.",
+        error
+      );
+    });
 }
 
 async function loadImage(content: Blob): Promise<string | ArrayBuffer | null> {
@@ -47,7 +113,8 @@ async function loadImage(content: Blob): Promise<string | ArrayBuffer | null> {
 async function makeRequest(
   request: sdk.Request,
   proxy: string | undefined,
-  _body: Body
+  _body: Body,
+  timeout: number = DEFAULT_REQUEST_TIMEOUT
 ) {
   const headers = request.toJSON().header;
 
@@ -194,7 +261,8 @@ async function makeRequest(
     finalUrl = normalizedProxy + request.url.toString();
   }
 
-  return fetchWithtimeout(finalUrl, requestOptions).then((response: any) => {
+  try {
+    const response = await fetchWithtimeout(finalUrl, requestOptions, timeout);
     const contentType = response.headers.get("content-type");
     let fileExtension = "";
 
@@ -224,32 +292,45 @@ async function makeRequest(
       }
 
       if (fileExtension) {
-        return response.blob().then((blob: any) => {
-          const url = window.URL.createObjectURL(blob);
+        const blob = await response.blob();
+        const url = window.URL.createObjectURL(blob);
 
-          const link = document.createElement("a");
-          link.href = url;
-          // Now the file name includes the extension
-          link.setAttribute("download", `file${fileExtension}`);
+        const link = document.createElement("a");
+        link.href = url;
+        // Now the file name includes the extension
+        link.setAttribute("download", `file${fileExtension}`);
 
-          // These two lines are necessary to make the link click in Firefox
-          link.style.display = "none";
-          document.body.appendChild(link);
+        // These two lines are necessary to make the link click in Firefox
+        link.style.display = "none";
+        document.body.appendChild(link);
 
-          link.click();
+        link.click();
 
-          // After link is clicked, it's safe to remove it.
-          setTimeout(() => document.body.removeChild(link), 0);
+        // After link is clicked, it's safe to remove it.
+        setTimeout(() => document.body.removeChild(link), 0);
 
-          return response;
-        });
+        return response;
       } else {
         return response;
       }
     }
 
     return response;
-  });
+  } catch (error) {
+    // Re-throw RequestError instances as-is
+    if (error instanceof RequestError) {
+      throw error;
+    }
+
+    // Wrap unexpected errors
+    throw new RequestError(
+      "unknown",
+      error instanceof Error
+        ? error.message
+        : "An unexpected error occurred while processing the response.",
+      error instanceof Error ? error : undefined
+    );
+  }
 }
 
 export default makeRequest;

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

@@ -9,12 +9,16 @@ import React from "react";
 
 import { useDoc } from "@docusaurus/plugin-content-docs/client";
 import { usePrismTheme } from "@docusaurus/theme-common";
+import { 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 clsx from "clsx";
 import { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
+import type { ThemeConfig } from "docusaurus-theme-openapi-docs/src/types";
 
 import { clearResponse, clearCode, clearHeaders } from "./slice";
 
@@ -40,7 +44,11 @@ function formatXml(xml: string) {
 
 function Response({ item }: { item: ApiItem }) {
   const metadata = useDoc();
+  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 prismTheme = usePrismTheme();
   const code = useTypedSelector((state: any) => state.response.code);
   const headers = useTypedSelector((state: any) => state.response.headers);
@@ -55,7 +63,7 @@ function Response({ item }: { item: ApiItem }) {
           ? "openapi-response__dot--success"
           : "openapi-response__dot--info");
 
-  if (!item.servers || hideSendButton) {
+  if ((!item.servers && !proxy) || hideSendButton) {
     return null;
   }
 
@@ -74,7 +82,9 @@ function Response({ item }: { item: ApiItem }) {
   return (
     <div className="openapi-explorer__response-container">
       <div className="openapi-explorer__response-title-container">
-        <span className="openapi-explorer__response-title">Response</span>
+        <span className="openapi-explorer__response-title">
+          {translate({ id: OPENAPI_RESPONSE.TITLE, message: "Response" })}
+        </span>
         <span
           className="openapi-explorer__response-clear-btn"
           onClick={() => {
@@ -83,7 +93,7 @@ function Response({ item }: { item: ApiItem }) {
             dispatch(clearHeaders());
           }}
         >
-          Clear
+          {translate({ id: OPENAPI_RESPONSE.CLEAR, message: "Clear" })}
         </span>
       </div>
       <div
@@ -117,14 +127,23 @@ function Response({ item }: { item: ApiItem }) {
               >
                 {prettyResponse || (
                   <p className="openapi-explorer__response-placeholder-message">
-                    Click the <code>Send API Request</code> button above and see
-                    the response here!
+                    {translate({
+                      id: OPENAPI_RESPONSE.PLACEHOLDER,
+                      message:
+                        "Click the <code>Send API Request</code> button above and see the response here!",
+                    })}
                   </p>
                 )}
               </ApiCodeBlock>
             </TabItem>
             {/* @ts-ignore */}
-            <TabItem label="Headers" value="headers">
+            <TabItem
+              label={translate({
+                id: OPENAPI_RESPONSE.HEADERS_TAB,
+                message: "Headers",
+              })}
+              value="headers"
+            >
               {/* @ts-ignore */}
               <ApiCodeBlock
                 className="openapi-explorer__code-block openapi-response__status-headers"
@@ -145,8 +164,11 @@ function Response({ item }: { item: ApiItem }) {
           </div>
         ) : (
           <p className="openapi-explorer__response-placeholder-message">
-            Click the <code>Send API Request</code> button above and see the
-            response here!
+            {translate({
+              id: OPENAPI_RESPONSE.PLACEHOLDER,
+              message:
+                "Click the <code>Send API Request</code> button above and see the response here!",
+            })}
           </p>
         )}
       </div>

package/src/theme/ApiExplorer/SchemaSelection/index.ts

@@ -0,0 +1,13 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+export {
+  default as schemaSelectionReducer,
+  setSchemaSelection,
+  clearSchemaSelections,
+} from "./slice";
+export type { SchemaSelectionState } from "./slice";

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

@@ -0,0 +1,46 @@
+/* ============================================================================
+ * 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";
+
+export interface SchemaSelectionState {
+  /**
+   * Maps schema path (e.g., "requestBody", "requestBody.anyOf.0.layer3")
+   * to the selected anyOf/oneOf option index
+   */
+  selections: { [schemaPath: string]: number };
+}
+
+const initialState: SchemaSelectionState = {
+  selections: {},
+};
+
+export const slice = createSlice({
+  name: "schemaSelection",
+  initialState,
+  reducers: {
+    /**
+     * Set the selected index for a specific schema path
+     */
+    setSchemaSelection: (
+      state,
+      action: PayloadAction<{ path: string; index: number }>
+    ) => {
+      state.selections[action.payload.path] = action.payload.index;
+    },
+    /**
+     * Clear all schema selections (useful when navigating to a new API endpoint)
+     */
+    clearSchemaSelections: (state) => {
+      state.selections = {};
+    },
+  },
+});
+
+export const { setSchemaSelection, clearSchemaSelections } = slice.actions;
+
+export default slice.reducer;