Skip to content

feat(theme): add requestCredentials option for API requests #1300

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sserrata merged 1 commit into from
Feb 2, 2026
Merged

feat(theme): add requestCredentials option for API requests #1300

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
},
},
}
Expand Down
12 changes: 7 additions & 5 deletions demo/docs/intro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
},
},
}
Expand Down
12 changes: 7 additions & 5 deletions packages/docusaurus-plugin-openapi-docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
},
},
}
Expand Down
4 changes: 3 additions & 1 deletion packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Request/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down Expand Up @@ -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);
Expand Down
4 changes: 3 additions & 1 deletion packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Request/makeRequest.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down Expand Up @@ -252,6 +253,7 @@ async function makeRequest(
method: request.method,
headers: myHeaders,
body: myBody,
...(credentials && { credentials }),
};

let finalUrl = request.url.toString();
Expand Down
7 changes: 7 additions & 0 deletions packages/docusaurus-theme-openapi-docs/src/types.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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";
};
}

Expand Down
Loading