docusaurus-theme-openapi-docs 4.5.0 → 4.6.0

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/SecuritySchemes/index.tsx

@@ -7,6 +7,9 @@
 
 import React from "react";
 
+import { translate } from "@docusaurus/Translate";
+import { OPENAPI_SECURITY_SCHEMES } from "@theme/translationIds";
+
 import Link from "@docusaurus/Link";
 import { useTypedSelector } from "@theme/ApiItem/hooks";
 
@@ -22,6 +25,41 @@ function SecuritySchemes(props: any) {
   }
 
   const selectedAuth = options[selected];
+
+  const keyTranslations: Record<string, { id: string; message: string }> = {
+    description: {
+      id: OPENAPI_SECURITY_SCHEMES.DESCRIPTION,
+      message: "description:",
+    },
+    scheme: {
+      id: OPENAPI_SECURITY_SCHEMES.SCHEME,
+      message: "scheme:",
+    },
+    bearerFormat: {
+      id: OPENAPI_SECURITY_SCHEMES.BEARER_FORMAT,
+      message: "bearerFormat:",
+    },
+    openIdConnectUrl: {
+      id: OPENAPI_SECURITY_SCHEMES.OPEN_ID_CONNECT_URL,
+      message: "openIdConnectUrl:",
+    },
+  };
+
+  const renderRest = (rest: Record<string, any>) =>
+    Object.keys(rest).map((k) => {
+      const translation = keyTranslations[k];
+      const label = translation
+        ? translate({ id: translation.id, message: translation.message })
+        : `${k}:`;
+      return (
+        <span key={k}>
+          <strong>{label} </strong>
+          {typeof rest[k] === "object"
+            ? JSON.stringify(rest[k], null, 2)
+            : String(rest[k])}
+        </span>
+      );
+    });
   return (
     <details className="openapi-security__details" open={false}>
       <summary className="openapi-security__summary-container">
@@ -48,31 +86,37 @@ function SecuritySchemes(props: any) {
                   }}
                 >
                   <span>
-                    <strong>name:</strong>{" "}
+                    <strong>
+                      {translate({
+                        id: OPENAPI_SECURITY_SCHEMES.NAME,
+                        message: "name:",
+                      })}
+                    </strong>{" "}
                     <Link to={infoAuthPath}>{name ?? key}</Link>
                   </span>
                   <span>
-                    <strong>type: </strong>
+                    <strong>
+                      {translate({
+                        id: OPENAPI_SECURITY_SCHEMES.TYPE,
+                        message: "type:",
+                      })}
+                    </strong>{" "}
                     {type}
                   </span>
                   {scopes && scopes.length > 0 && (
                     <span>
-                      <strong>scopes: </strong>
+                      <strong>
+                        {translate({
+                          id: OPENAPI_SECURITY_SCHEMES.SCOPES,
+                          message: "scopes:",
+                        })}
+                      </strong>{" "}
                       <code>
                         {auth.scopes.length > 0 ? auth.scopes.toString() : "[]"}
                       </code>
                     </span>
                   )}
-                  {Object.keys(rest).map((k, i) => {
-                    return (
-                      <span key={k}>
-                        <strong>{k}: </strong>
-                        {typeof rest[k] === "object"
-                          ? JSON.stringify(rest[k], null, 2)
-                          : String(rest[k])}
-                      </span>
-                    );
-                  })}
+                  {renderRest(rest)}
                 </pre>
               </React.Fragment>
             );
@@ -89,31 +133,37 @@ function SecuritySchemes(props: any) {
                   }}
                 >
                   <span>
-                    <strong>name:</strong>{" "}
+                    <strong>
+                      {translate({
+                        id: OPENAPI_SECURITY_SCHEMES.NAME,
+                        message: "name:",
+                      })}
+                    </strong>{" "}
                     <Link to={infoAuthPath}>{name ?? key}</Link>
                   </span>
                   <span>
-                    <strong>type: </strong>
+                    <strong>
+                      {translate({
+                        id: OPENAPI_SECURITY_SCHEMES.TYPE,
+                        message: "type:",
+                      })}
+                    </strong>{" "}
                     {type}
                   </span>
                   {scopes && scopes.length > 0 && (
                     <span>
-                      <strong>scopes: </strong>
+                      <strong>
+                        {translate({
+                          id: OPENAPI_SECURITY_SCHEMES.SCOPES,
+                          message: "scopes:",
+                        })}
+                      </strong>{" "}
                       <code>
                         {auth.scopes.length > 0 ? auth.scopes.toString() : "[]"}
                       </code>
                     </span>
                   )}
-                  {Object.keys(rest).map((k, i) => {
-                    return (
-                      <span key={k}>
-                        <strong>{k}: </strong>
-                        {typeof rest[k] === "object"
-                          ? JSON.stringify(rest[k], null, 2)
-                          : String(rest[k])}
-                      </span>
-                    );
-                  })}
+                  {renderRest(rest)}
                 </pre>
               </React.Fragment>
             );
@@ -128,15 +178,30 @@ function SecuritySchemes(props: any) {
                 }}
               >
                 <span>
-                  <strong>name:</strong>{" "}
+                  <strong>
+                    {translate({
+                      id: OPENAPI_SECURITY_SCHEMES.NAME,
+                      message: "name:",
+                    })}
+                  </strong>{" "}
                   <Link to={infoAuthPath}>{auth.name ?? auth.key}</Link>
                 </span>
                 <span>
-                  <strong>type: </strong>
+                  <strong>
+                    {translate({
+                      id: OPENAPI_SECURITY_SCHEMES.TYPE,
+                      message: "type:",
+                    })}
+                  </strong>{" "}
                   {auth.type}
                 </span>
                 <span>
-                  <strong>in: </strong>
+                  <strong>
+                    {translate({
+                      id: OPENAPI_SECURITY_SCHEMES.IN,
+                      message: "in:",
+                    })}
+                  </strong>{" "}
                   {auth.in}
                 </span>
               </pre>
@@ -156,31 +221,37 @@ function SecuritySchemes(props: any) {
                 }}
               >
                 <span>
-                  <strong>name:</strong>{" "}
+                  <strong>
+                    {translate({
+                      id: OPENAPI_SECURITY_SCHEMES.NAME,
+                      message: "name:",
+                    })}
+                  </strong>{" "}
                   <Link to={infoAuthPath}>{name ?? key}</Link>
                 </span>
                 <span>
-                  <strong>type: </strong>
+                  <strong>
+                    {translate({
+                      id: OPENAPI_SECURITY_SCHEMES.TYPE,
+                      message: "type:",
+                    })}
+                  </strong>{" "}
                   {type}
                 </span>
                 {scopes && scopes.length > 0 && (
                   <span>
-                    <strong>scopes: </strong>
+                    <strong>
+                      {translate({
+                        id: OPENAPI_SECURITY_SCHEMES.SCOPES,
+                        message: "scopes:",
+                      })}
+                    </strong>{" "}
                     <code>
                       {auth.scopes.length > 0 ? auth.scopes.toString() : "[]"}
                     </code>
                   </span>
                 )}
-                {Object.keys(rest).map((k, i) => {
-                  return (
-                    <span key={k}>
-                      <strong>{k}: </strong>
-                      {typeof rest[k] === "object"
-                        ? JSON.stringify(rest[k], null, 2)
-                        : String(rest[k])}
-                    </span>
-                  );
-                })}
+                {renderRest(rest)}
               </pre>
             </React.Fragment>
           );
@@ -198,35 +269,46 @@ function SecuritySchemes(props: any) {
                 }}
               >
                 <span>
-                  <strong>name:</strong>{" "}
+                  <strong>
+                    {translate({
+                      id: OPENAPI_SECURITY_SCHEMES.NAME,
+                      message: "name:",
+                    })}
+                  </strong>{" "}
                   <Link to={infoAuthPath}>{name ?? key}</Link>
                 </span>
                 <span>
-                  <strong>type: </strong>
+                  <strong>
+                    {translate({
+                      id: OPENAPI_SECURITY_SCHEMES.TYPE,
+                      message: "type:",
+                    })}
+                  </strong>{" "}
                   {type}
                 </span>
                 {scopes && scopes.length > 0 && (
                   <span>
-                    <strong>scopes: </strong>
+                    <strong>
+                      {translate({
+                        id: OPENAPI_SECURITY_SCHEMES.SCOPES,
+                        message: "scopes:",
+                      })}
+                    </strong>{" "}
                     <code>
                       {auth.scopes.length > 0 ? auth.scopes.toString() : "[]"}
                     </code>
                   </span>
                 )}
-                {Object.keys(rest).map((k, i) => {
-                  return (
-                    <span key={k}>
-                      <strong>{k}: </strong>
-                      {typeof rest[k] === "object"
-                        ? JSON.stringify(rest[k], null, 2)
-                        : String(rest[k])}
-                    </span>
-                  );
-                })}
+                {renderRest(rest)}
                 {flows && (
                   <span>
                     <code>
-                      <strong>flows: </strong>
+                      <strong>
+                        {translate({
+                          id: OPENAPI_SECURITY_SCHEMES.FLOWS,
+                          message: "flows:",
+                        })}
+                      </strong>{" "}
                       {JSON.stringify(flows, null, 2)}
                     </code>
                   </span>
@@ -248,31 +330,37 @@ function SecuritySchemes(props: any) {
                 }}
               >
                 <span>
-                  <strong>name:</strong>{" "}
+                  <strong>
+                    {translate({
+                      id: OPENAPI_SECURITY_SCHEMES.NAME,
+                      message: "name:",
+                    })}
+                  </strong>{" "}
                   <Link to={infoAuthPath}>{name ?? key}</Link>
                 </span>
                 <span>
-                  <strong>type: </strong>
+                  <strong>
+                    {translate({
+                      id: OPENAPI_SECURITY_SCHEMES.TYPE,
+                      message: "type:",
+                    })}
+                  </strong>{" "}
                   {type}
                 </span>
                 {scopes && scopes.length > 0 && (
                   <span>
-                    <strong>scopes: </strong>
+                    <strong>
+                      {translate({
+                        id: OPENAPI_SECURITY_SCHEMES.SCOPES,
+                        message: "scopes:",
+                      })}
+                    </strong>{" "}
                     <code>
                       {auth.scopes.length > 0 ? auth.scopes.toString() : "[]"}
                     </code>
                   </span>
                 )}
-                {Object.keys(rest).map((k, i) => {
-                  return (
-                    <span key={k}>
-                      <strong>{k}: </strong>
-                      {typeof rest[k] === "object"
-                        ? JSON.stringify(rest[k], null, 2)
-                        : String(rest[k])}
-                    </span>
-                  );
-                })}
+                {renderRest(rest)}
               </pre>
             </React.Fragment>
           );

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

@@ -7,11 +7,13 @@
 
 import React, { useState } from "react";
 
+import { translate } from "@docusaurus/Translate";
 import FloatingButton from "@theme/ApiExplorer/FloatingButton";
 import FormItem from "@theme/ApiExplorer/FormItem";
 import FormSelect from "@theme/ApiExplorer/FormSelect";
 import FormTextInput from "@theme/ApiExplorer/FormTextInput";
 import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
+import { OPENAPI_SERVER } from "@theme/translationIds";
 
 import { setServer, setServerVariable } from "./slice";
 
@@ -57,7 +59,10 @@ function Server() {
       }
     }
     return (
-      <FloatingButton onClick={() => setIsEditing(true)} label="Edit">
+      <FloatingButton
+        onClick={() => setIsEditing(true)}
+        label={translate({ id: OPENAPI_SERVER.EDIT_BUTTON, message: "Edit" })}
+      >
         <FormItem>
           <span className="openapi-explorer__server-url" title={url}>
             {url}
@@ -68,11 +73,14 @@ function Server() {
   }
   return (
     <div className="openapi-explorer__server-container">
-      <FloatingButton onClick={() => setIsEditing(false)} label="Hide">
+      <FloatingButton
+        onClick={() => setIsEditing(false)}
+        label={translate({ id: OPENAPI_SERVER.HIDE_BUTTON, message: "Hide" })}
+      >
         <FormItem>
           <FormSelect
             options={options.map((s: any) => s.url)}
-            onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
+            onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
               dispatch(
                 setServer(
                   JSON.stringify(
@@ -94,7 +102,7 @@ function Server() {
                 <FormItem label={key}>
                   <FormSelect
                     options={value.variables[key].enum}
-                    onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
+                    onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
                       dispatch(
                         setServerVariable(
                           JSON.stringify({ key, value: e.target.value })