docusaurus-theme-openapi-docs 4.5.0 → 4.6.0

package/lib/theme/ApiExplorer/Request/index.js

@@ -70,6 +70,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // @ts-nocheck
 const react_1 = __importStar(require("react"));
 const client_1 = require("@docusaurus/plugin-content-docs/client");
+const Translate_1 = require("@docusaurus/Translate");
+const useDocusaurusContext_1 = __importDefault(
+  require("@docusaurus/useDocusaurusContext")
+);
 const Accept_1 = __importDefault(require("@theme/ApiExplorer/Accept"));
 const Authorization_1 = __importDefault(
   require("@theme/ApiExplorer/Authorization")
@@ -87,13 +91,20 @@ const ParamOptions_1 = __importDefault(
 const slice_1 = require("@theme/ApiExplorer/Response/slice");
 const Server_1 = __importDefault(require("@theme/ApiExplorer/Server"));
 const hooks_1 = require("@theme/ApiItem/hooks");
+const translationIds_1 = require("@theme/translationIds");
 const sdk = __importStar(require("postman-collection"));
 const react_hook_form_1 = require("react-hook-form");
-const makeRequest_1 = __importDefault(require("./makeRequest"));
+const makeRequest_1 = __importStar(require("./makeRequest"));
 function Request({ item }) {
   const postman = new sdk.Request(item.postman);
   const metadata = (0, client_1.useDoc)();
-  const { proxy, hide_send_button: hideSendButton } = metadata.frontMatter;
+  const { proxy: frontMatterProxy, hide_send_button: hideSendButton } =
+    metadata.frontMatter;
+  const { siteConfig } = (0, useDocusaurusContext_1.default)();
+  const themeConfig = siteConfig.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 = (0, hooks_1.useTypedSelector)(
     (state) => state.params.path
   );
@@ -178,11 +189,52 @@ function Request({ item }) {
     res.headers &&
       dispatch((0, slice_1.setHeaders)(Object.fromEntries(res.headers)));
   };
+  const getErrorMessage = (errorType) => {
+    switch (errorType) {
+      case "timeout":
+        return (0, Translate_1.translate)({
+          id: translationIds_1.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 (0, Translate_1.translate)({
+          id: translationIds_1.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 (0, Translate_1.translate)({
+          id: translationIds_1.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 (0, Translate_1.translate)({
+          id: translationIds_1.OPENAPI_REQUEST.ERROR_UNKNOWN,
+          message:
+            "An unexpected error occurred while making the request. Please try again.",
+        });
+    }
+  };
   const onSubmit = async (data) => {
-    dispatch((0, slice_1.setResponse)("Fetching..."));
+    dispatch(
+      (0, slice_1.setResponse)(
+        (0, Translate_1.translate)({
+          id: translationIds_1.OPENAPI_REQUEST.FETCHING_MESSAGE,
+          message: "Fetching...",
+        })
+      )
+    );
     try {
       await delay(1200);
-      const res = await (0, makeRequest_1.default)(postmanRequest, proxy, body);
+      const res = await (0, makeRequest_1.default)(
+        postmanRequest,
+        proxy,
+        body,
+        requestTimeout
+      );
       if (res.headers.get("content-type")?.includes("text/event-stream")) {
         await handleEventStream(res);
       } else {
@@ -190,7 +242,16 @@ function Request({ item }) {
       }
     } catch (e) {
       console.log(e);
-      dispatch((0, slice_1.setResponse)("Connection failed"));
+      let errorMessage;
+      if (e instanceof makeRequest_1.RequestError) {
+        errorMessage = getErrorMessage(e.type);
+      } else {
+        errorMessage = (0, Translate_1.translate)({
+          id: translationIds_1.OPENAPI_REQUEST.CONNECTION_FAILED,
+          message: "Connection failed",
+        });
+      }
+      dispatch((0, slice_1.setResponse)(errorMessage));
       dispatch((0, slice_1.clearCode)());
       dispatch((0, slice_1.clearHeaders)());
     }
@@ -198,7 +259,7 @@ function Request({ item }) {
   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;
@@ -207,7 +268,8 @@ function Request({ item }) {
     !showAuth &&
     !showParams &&
     !showRequestBody &&
-    !showServerOptions
+    !showServerOptions &&
+    !showRequestButton
   ) {
     return null;
   }
@@ -242,7 +304,10 @@ function Request({ item }) {
         react_1.default.createElement(
           "span",
           { className: "openapi-explorer__request-title" },
-          "Request "
+          (0, Translate_1.translate)({
+            id: translationIds_1.OPENAPI_REQUEST.REQUEST_TITLE,
+            message: "Request",
+          })
         ),
         allDetailsExpanded
           ? react_1.default.createElement(
@@ -251,7 +316,10 @@ function Request({ item }) {
                 className: "openapi-explorer__expand-details-btn",
                 onClick: collapseAllDetails,
               },
-              "Collapse all"
+              (0, Translate_1.translate)({
+                id: translationIds_1.OPENAPI_REQUEST.COLLAPSE_ALL,
+                message: "Collapse all",
+              })
             )
           : react_1.default.createElement(
               "span",
@@ -259,7 +327,10 @@ function Request({ item }) {
                 className: "openapi-explorer__expand-details-btn",
                 onClick: expandAllDetails,
               },
-              "Expand all"
+              (0, Translate_1.translate)({
+                id: translationIds_1.OPENAPI_REQUEST.EXPAND_ALL,
+                message: "Expand all",
+              })
             )
       ),
       react_1.default.createElement(
@@ -282,7 +353,10 @@ function Request({ item }) {
                   setExpandServer(!expandServer);
                 },
               },
-              "Base URL"
+              (0, Translate_1.translate)({
+                id: translationIds_1.OPENAPI_REQUEST.BASE_URL_TITLE,
+                message: "Base URL",
+              })
             ),
             react_1.default.createElement(Server_1.default, null)
           ),
@@ -302,7 +376,10 @@ function Request({ item }) {
                   setExpandAuth(!expandAuth);
                 },
               },
-              "Auth"
+              (0, Translate_1.translate)({
+                id: translationIds_1.OPENAPI_REQUEST.AUTH_TITLE,
+                message: "Auth",
+              })
             ),
             react_1.default.createElement(Authorization_1.default, null)
           ),
@@ -323,7 +400,10 @@ function Request({ item }) {
                   setExpandParams(!expandParams);
                 },
               },
-              "Parameters"
+              (0, Translate_1.translate)({
+                id: translationIds_1.OPENAPI_REQUEST.PARAMETERS_TITLE,
+                message: "Parameters",
+              })
             ),
             react_1.default.createElement(ParamOptions_1.default, null)
           ),
@@ -343,12 +423,19 @@ function Request({ item }) {
                   setExpandBody(!expandBody);
                 },
               },
-              "Body",
+              (0, Translate_1.translate)({
+                id: translationIds_1.OPENAPI_REQUEST.BODY_TITLE,
+                message: "Body",
+              }),
               requestBodyRequired &&
                 react_1.default.createElement(
                   "span",
                   { className: "openapi-schema__required" },
-                  "\u00A0required"
+                  "\u00A0",
+                  (0, Translate_1.translate)({
+                    id: translationIds_1.OPENAPI_REQUEST.REQUIRED_LABEL,
+                    message: "required",
+                  })
                 )
             ),
             react_1.default.createElement(
@@ -378,7 +465,10 @@ function Request({ item }) {
                   setExpandAccept(!expandAccept);
                 },
               },
-              "Accept"
+              (0, Translate_1.translate)({
+                id: translationIds_1.OPENAPI_REQUEST.ACCEPT_TITLE,
+                message: "Accept",
+              })
             ),
             react_1.default.createElement(Accept_1.default, null)
           ),
@@ -387,7 +477,10 @@ function Request({ item }) {
           react_1.default.createElement(
             "button",
             { className: "openapi-explorer__request-btn", type: "submit" },
-            "Send API Request"
+            (0, Translate_1.translate)({
+              id: translationIds_1.OPENAPI_REQUEST.SEND_BUTTON,
+              message: "Send API Request",
+            })
           )
       )
     )

package/lib/theme/ApiExplorer/Request/makeRequest.d.ts

@@ -1,4 +1,10 @@
 import { Body } from "@theme/ApiExplorer/Body/slice";
 import * as sdk from "postman-collection";
-declare function makeRequest(request: sdk.Request, proxy: string | undefined, _body: Body): Promise<any>;
+export type RequestErrorType = "timeout" | "network" | "cors" | "abort" | "unknown";
+export declare class RequestError extends Error {
+    type: RequestErrorType;
+    originalError?: Error;
+    constructor(type: RequestErrorType, message: string, originalError?: Error);
+}
+declare function makeRequest(request: sdk.Request, proxy: string | undefined, _body: Body, timeout?: number): Promise<Response>;
 export default makeRequest;

package/lib/theme/ApiExplorer/Request/makeRequest.js

@@ -6,13 +6,65 @@
  * LICENSE file in the root directory of this source tree.
  * ========================================================================== */
 Object.defineProperty(exports, "__esModule", { value: true });
-function fetchWithtimeout(url, options, timeout = 5000) {
-  return Promise.race([
-    fetch(url, options),
-    new Promise((_, reject) =>
-      setTimeout(() => reject(new Error("Request timed out")), timeout)
-    ),
-  ]);
+exports.RequestError = void 0;
+class RequestError extends Error {
+  type;
+  originalError;
+  constructor(type, message, originalError) {
+    super(message);
+    this.name = "RequestError";
+    this.type = type;
+    this.originalError = originalError;
+  }
+}
+exports.RequestError = RequestError;
+const DEFAULT_REQUEST_TIMEOUT = 30000; // 30 seconds
+function fetchWithtimeout(url, options, timeout = DEFAULT_REQUEST_TIMEOUT) {
+  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) {
   return new Promise((accept, reject) => {
@@ -33,7 +85,12 @@ async function loadImage(content) {
     reader.readAsArrayBuffer(content);
   });
 }
-async function makeRequest(request, proxy, _body) {
+async function makeRequest(
+  request,
+  proxy,
+  _body,
+  timeout = DEFAULT_REQUEST_TIMEOUT
+) {
   const headers = request.toJSON().header;
   let myHeaders = new Headers();
   if (headers) {
@@ -171,7 +228,8 @@ async function makeRequest(request, proxy, _body) {
     let normalizedProxy = proxy.replace(/\/$/, "") + "/";
     finalUrl = normalizedProxy + request.url.toString();
   }
-  return fetchWithtimeout(finalUrl, requestOptions).then((response) => {
+  try {
+    const response = await fetchWithtimeout(finalUrl, requestOptions, timeout);
     const contentType = response.headers.get("content-type");
     let fileExtension = "";
     if (contentType) {
@@ -199,25 +257,37 @@ async function makeRequest(request, proxy, _body) {
         fileExtension = ".zip";
       }
       if (fileExtension) {
-        return response.blob().then((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}`);
-          // These two lines are necessary to make the link click in Firefox
-          link.style.display = "none";
-          document.body.appendChild(link);
-          link.click();
-          // After link is clicked, it's safe to remove it.
-          setTimeout(() => document.body.removeChild(link), 0);
-          return response;
-        });
+        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}`);
+        // These two lines are necessary to make the link click in Firefox
+        link.style.display = "none";
+        document.body.appendChild(link);
+        link.click();
+        // After link is clicked, it's safe to remove it.
+        setTimeout(() => document.body.removeChild(link), 0);
+        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
+    );
+  }
 }
 exports.default = makeRequest;

package/lib/theme/ApiExplorer/Response/index.js

@@ -14,12 +14,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const react_1 = __importDefault(require("react"));
 const client_1 = require("@docusaurus/plugin-content-docs/client");
 const theme_common_1 = require("@docusaurus/theme-common");
+const Translate_1 = require("@docusaurus/Translate");
+const useDocusaurusContext_1 = __importDefault(
+  require("@docusaurus/useDocusaurusContext")
+);
 const ApiCodeBlock_1 = __importDefault(
   require("@theme/ApiExplorer/ApiCodeBlock")
 );
 const hooks_1 = require("@theme/ApiItem/hooks");
 const SchemaTabs_1 = __importDefault(require("@theme/SchemaTabs"));
 const TabItem_1 = __importDefault(require("@theme/TabItem"));
+const translationIds_1 = require("@theme/translationIds");
 const clsx_1 = __importDefault(require("clsx"));
 const slice_1 = require("./slice");
 // TODO: We probably shouldn't attempt to format XML...
@@ -42,7 +47,10 @@ function formatXml(xml) {
 }
 function Response({ item }) {
   const metadata = (0, client_1.useDoc)();
+  const { siteConfig } = (0, useDocusaurusContext_1.default)();
+  const themeConfig = siteConfig.themeConfig;
   const hideSendButton = metadata.frontMatter.hide_send_button;
+  const proxy = metadata.frontMatter.proxy ?? themeConfig.api?.proxy;
   const prismTheme = (0, theme_common_1.usePrismTheme)();
   const code = (0, hooks_1.useTypedSelector)((state) => state.response.code);
   const headers = (0, hooks_1.useTypedSelector)(
@@ -60,7 +68,7 @@ function Response({ item }) {
         : parseInt(code) >= 200 && parseInt(code) < 300
           ? "openapi-response__dot--success"
           : "openapi-response__dot--info");
-  if (!item.servers || hideSendButton) {
+  if ((!item.servers && !proxy) || hideSendButton) {
     return null;
   }
   let prettyResponse = response;
@@ -82,7 +90,10 @@ function Response({ item }) {
       react_1.default.createElement(
         "span",
         { className: "openapi-explorer__response-title" },
-        "Response"
+        (0, Translate_1.translate)({
+          id: translationIds_1.OPENAPI_RESPONSE.TITLE,
+          message: "Response",
+        })
       ),
       react_1.default.createElement(
         "span",
@@ -94,7 +105,10 @@ function Response({ item }) {
             dispatch((0, slice_1.clearHeaders)());
           },
         },
-        "Clear"
+        (0, Translate_1.translate)({
+          id: translationIds_1.OPENAPI_RESPONSE.CLEAR,
+          message: "Clear",
+        })
       )
     ),
     react_1.default.createElement(
@@ -143,19 +157,23 @@ function Response({ item }) {
                       className:
                         "openapi-explorer__response-placeholder-message",
                     },
-                    "Click the ",
-                    react_1.default.createElement(
-                      "code",
-                      null,
-                      "Send API Request"
-                    ),
-                    " button above and see the response here!"
+                    (0, Translate_1.translate)({
+                      id: translationIds_1.OPENAPI_RESPONSE.PLACEHOLDER,
+                      message:
+                        "Click the <code>Send API Request</code> button above and see the response here!",
+                    })
                   )
               )
             ),
             react_1.default.createElement(
               TabItem_1.default,
-              { label: "Headers", value: "headers" },
+              {
+                label: (0, Translate_1.translate)({
+                  id: translationIds_1.OPENAPI_RESPONSE.HEADERS_TAB,
+                  message: "Headers",
+                }),
+                value: "headers",
+              },
               react_1.default.createElement(
                 ApiCodeBlock_1.default,
                 {
@@ -183,9 +201,11 @@ function Response({ item }) {
           : react_1.default.createElement(
               "p",
               { className: "openapi-explorer__response-placeholder-message" },
-              "Click the ",
-              react_1.default.createElement("code", null, "Send API Request"),
-              " button above and see the response here!"
+              (0, Translate_1.translate)({
+                id: translationIds_1.OPENAPI_RESPONSE.PLACEHOLDER,
+                message:
+                  "Click the <code>Send API Request</code> button above and see the response here!",
+              })
             )
     )
   );

package/lib/theme/ApiExplorer/Response/slice.d.ts

@@ -5,13 +5,37 @@ export interface State {
     headers?: string;
 }
 export declare const slice: import("@reduxjs/toolkit").Slice<State, {
-    setResponse: (state: import("immer/dist/internal").WritableDraft<State>, action: PayloadAction<string>) => void;
-    setCode: (state: import("immer/dist/internal").WritableDraft<State>, action: PayloadAction<string>) => void;
-    setHeaders: (state: import("immer/dist/internal").WritableDraft<State>, action: PayloadAction<string>) => void;
-    clearResponse: (state: import("immer/dist/internal").WritableDraft<State>) => void;
-    clearCode: (state: import("immer/dist/internal").WritableDraft<State>) => void;
-    clearHeaders: (state: import("immer/dist/internal").WritableDraft<State>) => void;
-}, "response">;
+    setResponse: (state: {
+        value?: string | undefined;
+        code?: string | undefined;
+        headers?: string | undefined;
+    }, action: PayloadAction<string>) => void;
+    setCode: (state: {
+        value?: string | undefined;
+        code?: string | undefined;
+        headers?: string | undefined;
+    }, action: PayloadAction<string>) => void;
+    setHeaders: (state: {
+        value?: string | undefined;
+        code?: string | undefined;
+        headers?: string | undefined;
+    }, action: PayloadAction<string>) => void;
+    clearResponse: (state: {
+        value?: string | undefined;
+        code?: string | undefined;
+        headers?: string | undefined;
+    }) => void;
+    clearCode: (state: {
+        value?: string | undefined;
+        code?: string | undefined;
+        headers?: string | undefined;
+    }) => void;
+    clearHeaders: (state: {
+        value?: string | undefined;
+        code?: string | undefined;
+        headers?: string | undefined;
+    }) => void;
+}, "response", "response", import("@reduxjs/toolkit").SliceSelectors<State>>;
 export declare const setResponse: import("@reduxjs/toolkit").ActionCreatorWithPayload<string, "response/setResponse">, clearResponse: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"response/clearResponse">, setCode: import("@reduxjs/toolkit").ActionCreatorWithPayload<string, "response/setCode">, clearCode: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"response/clearCode">, setHeaders: import("@reduxjs/toolkit").ActionCreatorWithPayload<string, "response/setHeaders">, clearHeaders: import("@reduxjs/toolkit").ActionCreatorWithoutPayload<"response/clearHeaders">;
 declare const _default: import("redux").Reducer<State>;
 export default _default;