From b08ca76141da75c2688bbe21d571f9ebdcca90e7 Mon Sep 17 00:00:00 2001 From: Steven Serrata Date: Mon, 2 Feb 2026 13:07:18 -0500 Subject: [PATCH] feat(theme): add requestCredentials option for API requests Add a new `requestCredentials` configuration option to control cookie and credential behavior in ApiExplorer requests. This is useful when API documentation is hosted on the same domain as the application, where browsers automatically include session cookies. Options: - "omit": Never send cookies - "same-origin": Send cookies for same-origin requests (browser default) - "include": Always send cookies, even for cross-origin Usage in docusaurus.config.js: ```js themeConfig: { api: { requestCredentials: "omit", }, }, ``` Fixes #1296 --- README.md | 12 +++++++----- demo/docs/intro.mdx | 12 +++++++----- packages/docusaurus-plugin-openapi-docs/README.md | 12 +++++++----- .../src/theme/ApiExplorer/Request/index.tsx | 4 +++- .../src/theme/ApiExplorer/Request/makeRequest.ts | 4 +++- .../docusaurus-theme-openapi-docs/src/types.d.ts | 7 +++++++ 6 files changed, 34 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index b0a6ac61f..f30a132d3 100644 --- a/README.md +++ b/README.md @@ -251,11 +251,12 @@ petstore: { The `docusaurus-theme-openapi-docs` theme can be configured with the following options in `themeConfig.api`: -| Name | Type | Default | Description | -| ----------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `proxy` | `string` | `null` | _Optional:_ Site-wide proxy URL to prepend to base URL when performing API requests. Can be overridden per-spec via plugin config. | -| `authPersistance` | `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. | -| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. | +| Name | Type | Default | Description | +| -------------------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `proxy` | `string` | `null` | _Optional:_ Site-wide proxy URL to prepend to base URL when performing API requests. Can be overridden per-spec via plugin config. | +| `authPersistance` | `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. | +| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. | +| `requestCredentials` | `string` | `"same-origin"` | _Optional:_ Controls cookie behavior for API requests. Options: `"omit"`, `"same-origin"`, or `"include"`. | Example: @@ -267,6 +268,7 @@ Example: proxy: "https://cors.pan.dev", // Site-wide proxy (can be overridden per-spec in plugin config) authPersistance: "localStorage", requestTimeout: 60000, // 60 seconds + requestCredentials: "omit", // Prevent cookies from being sent with requests }, }, } diff --git a/demo/docs/intro.mdx b/demo/docs/intro.mdx index b543cb55e..4c2b16349 100644 --- a/demo/docs/intro.mdx +++ b/demo/docs/intro.mdx @@ -315,11 +315,12 @@ petstore: { The `docusaurus-theme-openapi-docs` theme can be configured with the following options in `themeConfig.api`: -| Name | Type | Default | Description | -| ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| `proxy` | `string` | `null` | _Optional:_ Site-wide proxy URL to prepend to base URL when performing API requests. Can be overridden per-spec via plugin config. | -| `authPersistance`| `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. | -| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. | +| Name | Type | Default | Description | +| -------------------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `proxy` | `string` | `null` | _Optional:_ Site-wide proxy URL to prepend to base URL when performing API requests. Can be overridden per-spec via plugin config. | +| `authPersistance` | `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. | +| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. | +| `requestCredentials` | `string` | `"same-origin"` | _Optional:_ Controls cookie behavior for API requests. Options: `"omit"`, `"same-origin"`, or `"include"`. | Example: @@ -331,6 +332,7 @@ Example: proxy: "https://cors.pan.dev", // Site-wide proxy (can be overridden per-spec in plugin config) authPersistance: "localStorage", requestTimeout: 60000, // 60 seconds + requestCredentials: "omit", // Prevent cookies from being sent with requests }, }, } diff --git a/packages/docusaurus-plugin-openapi-docs/README.md b/packages/docusaurus-plugin-openapi-docs/README.md index 3a7da65ba..4c8a619f6 100644 --- a/packages/docusaurus-plugin-openapi-docs/README.md +++ b/packages/docusaurus-plugin-openapi-docs/README.md @@ -253,11 +253,12 @@ petstore: { The `docusaurus-theme-openapi-docs` theme can be configured with the following options in `themeConfig.api`: -| Name | Type | Default | Description | -| ----------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `proxy` | `string` | `null` | _Optional:_ Site-wide proxy URL to prepend to base URL when performing API requests. Can be overridden per-spec via plugin config. | -| `authPersistance` | `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. | -| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. | +| Name | Type | Default | Description | +| -------------------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `proxy` | `string` | `null` | _Optional:_ Site-wide proxy URL to prepend to base URL when performing API requests. Can be overridden per-spec via plugin config. | +| `authPersistance` | `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. | +| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. | +| `requestCredentials` | `string` | `"same-origin"` | _Optional:_ Controls cookie behavior for API requests. Options: `"omit"`, `"same-origin"`, or `"include"`. | Example: @@ -269,6 +270,7 @@ Example: proxy: "https://cors.pan.dev", // Site-wide proxy (can be overridden per-spec in plugin config) authPersistance: "localStorage", requestTimeout: 60000, // 60 seconds + requestCredentials: "omit", // Prevent cookies from being sent with requests }, }, } diff --git a/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Request/index.tsx b/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Request/index.tsx index 97c1a5782..74289439b 100644 --- a/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Request/index.tsx +++ b/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Request/index.tsx @@ -43,6 +43,7 @@ function Request({ item }: { item: ApiItem }) { const { siteConfig } = useDocusaurusContext(); const themeConfig = siteConfig.themeConfig as ThemeConfig; const requestTimeout = themeConfig.api?.requestTimeout; + const requestCredentials = themeConfig.api?.requestCredentials; // Frontmatter proxy (per-spec) takes precedence over theme config proxy (site-wide) const proxy = frontMatterProxy ?? themeConfig.api?.proxy; @@ -171,7 +172,8 @@ function Request({ item }: { item: ApiItem }) { postmanRequest, proxy, body, - requestTimeout + requestTimeout, + requestCredentials ); if (res.headers.get("content-type")?.includes("text/event-stream")) { await handleEventStream(res); diff --git a/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Request/makeRequest.ts b/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Request/makeRequest.ts index 914311703..5770d1ef0 100644 --- a/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Request/makeRequest.ts +++ b/packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Request/makeRequest.ts @@ -114,7 +114,8 @@ async function makeRequest( request: sdk.Request, proxy: string | undefined, _body: Body, - timeout: number = DEFAULT_REQUEST_TIMEOUT + timeout: number = DEFAULT_REQUEST_TIMEOUT, + credentials?: RequestCredentials ) { const headers = request.toJSON().header; @@ -252,6 +253,7 @@ async function makeRequest( method: request.method, headers: myHeaders, body: myBody, + ...(credentials && { credentials }), }; let finalUrl = request.url.toString(); diff --git a/packages/docusaurus-theme-openapi-docs/src/types.d.ts b/packages/docusaurus-theme-openapi-docs/src/types.d.ts index 349e8bea1..0afd06934 100644 --- a/packages/docusaurus-theme-openapi-docs/src/types.d.ts +++ b/packages/docusaurus-theme-openapi-docs/src/types.d.ts @@ -27,6 +27,13 @@ export interface ThemeConfig { authPersistence?: false | "sessionStorage" | "localStorage"; /** Request timeout in milliseconds. Defaults to 30000 (30 seconds). */ requestTimeout?: number; + /** + * Controls whether cookies and credentials are sent with API requests. + * - `"omit"`: Never send cookies (useful when docs are on same domain as app) + * - `"same-origin"`: Send cookies for same-origin requests (default browser behavior) + * - `"include"`: Always send cookies, even for cross-origin requests + */ + requestCredentials?: "omit" | "same-origin" | "include"; }; }