docusaurus-theme-openapi-docs 0.0.0-1074 → 0.0.0-1076

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

@@ -71,6 +71,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 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")
@@ -91,11 +94,17 @@ 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
   );
@@ -180,6 +189,35 @@ 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)(
@@ -191,7 +229,12 @@ function Request({ item }) {
     );
     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 {
@@ -199,14 +242,16 @@ function Request({ item }) {
       }
     } catch (e) {
       console.log(e);
-      dispatch(
-        (0, slice_1.setResponse)(
-          (0, Translate_1.translate)({
-            id: translationIds_1.OPENAPI_REQUEST.CONNECTION_FAILED,
-            message: "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)());
     }

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/translationIds.d.ts

@@ -20,6 +20,10 @@ export declare const OPENAPI_REQUEST: {
     PARAMETERS_TITLE: string;
     FETCHING_MESSAGE: string;
     CONNECTION_FAILED: string;
+    ERROR_TIMEOUT: string;
+    ERROR_NETWORK: string;
+    ERROR_CORS: string;
+    ERROR_UNKNOWN: string;
 };
 export declare const OPENAPI_SERVER: {
     EDIT_BUTTON: string;

package/lib/theme/translationIds.js

@@ -43,6 +43,10 @@ exports.OPENAPI_REQUEST = {
   PARAMETERS_TITLE: "theme.openapi.request.parameters.title",
   FETCHING_MESSAGE: "theme.openapi.request.fetchingMessage",
   CONNECTION_FAILED: "theme.openapi.request.connectionFailed",
+  ERROR_TIMEOUT: "theme.openapi.request.error.timeout",
+  ERROR_NETWORK: "theme.openapi.request.error.network",
+  ERROR_CORS: "theme.openapi.request.error.cors",
+  ERROR_UNKNOWN: "theme.openapi.request.error.unknown",
 };
 exports.OPENAPI_SERVER = {
   EDIT_BUTTON: "theme.openapi.server.editButton",

package/lib/types.d.ts

@@ -4,6 +4,8 @@ export interface ThemeConfig {
     api?: {
         proxy?: string;
         authPersistance?: false | "localStorage" | "sessionStorage";
+        /** Request timeout in milliseconds. Defaults to 30000 (30 seconds). */
+        requestTimeout?: number;
     };
 }
 export type JSONSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-theme-openapi-docs",
   "description": "OpenAPI theme for Docusaurus.",
-  "version": "0.0.0-1074",
+  "version": "0.0.0-1076",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -38,7 +38,7 @@
     "@types/postman-collection": "^3.5.11",
     "@types/react-modal": "^3.16.3",
     "concurrently": "^9.2.0",
-    "docusaurus-plugin-openapi-docs": "0.0.0-1074",
+    "docusaurus-plugin-openapi-docs": "0.0.0-1076",
     "docusaurus-plugin-sass": "^0.2.6",
     "eslint-plugin-prettier": "^5.5.1"
   },
@@ -81,5 +81,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "3d60239f7cc168258b19fb137135df436ce5ab44"
+  "gitHead": "c5c4370633dd11b143393c1bcda342b49816e15a"
 }

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

@@ -10,6 +10,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 type { ThemeConfig } from "docusaurus-theme-openapi-docs/src/types";
 import Accept from "@theme/ApiExplorer/Accept";
 import Authorization from "@theme/ApiExplorer/Authorization";
 import Body from "@theme/ApiExplorer/Body";
@@ -31,12 +33,18 @@ import { ApiItem } from "docusaurus-plugin-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);
@@ -118,6 +126,36 @@ 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(
@@ -129,7 +167,12 @@ function Request({ item }: { item: ApiItem }) {
     );
     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 {
@@ -137,14 +180,18 @@ function Request({ item }: { item: ApiItem }) {
       }
     } catch (e) {
       console.log(e);
-      dispatch(
-        setResponse(
-          translate({
-            id: OPENAPI_REQUEST.CONNECTION_FAILED,
-            message: "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());
     }

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/translationIds.ts

@@ -29,6 +29,10 @@ export const OPENAPI_REQUEST = {
   PARAMETERS_TITLE: "theme.openapi.request.parameters.title",
   FETCHING_MESSAGE: "theme.openapi.request.fetchingMessage",
   CONNECTION_FAILED: "theme.openapi.request.connectionFailed",
+  ERROR_TIMEOUT: "theme.openapi.request.error.timeout",
+  ERROR_NETWORK: "theme.openapi.request.error.network",
+  ERROR_CORS: "theme.openapi.request.error.cors",
+  ERROR_UNKNOWN: "theme.openapi.request.error.unknown",
 };
 
 export const OPENAPI_SERVER = {

package/src/types.ts

@@ -12,6 +12,8 @@ export interface ThemeConfig {
   api?: {
     proxy?: string;
     authPersistance?: false | "localStorage" | "sessionStorage";
+    /** Request timeout in milliseconds. Defaults to 30000 (30 seconds). */
+    requestTimeout?: number;
   };
 }