Skip to content

Commit 0f643dd

Browse files
sserratasserrata
authored
feat(theme): add requestCredentials option for API requests (#1300)
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
1 parent d7f8454 commit 0f643dd

File tree

6 files changed

+34
-17
lines changed

6 files changed

+34
-17
lines changed

‎README.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -251,11 +251,12 @@ petstore: {
251251

252252
The `docusaurus-theme-openapi-docs` theme can be configured with the following options in `themeConfig.api`:
253253

254-
| Name | Type | Default | Description |
255-
| ----------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
256-
| `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. |
257-
| `authPersistance` | `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. |
258-
| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. |
254+
| Name | Type | Default | Description |
255+
| -------------------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
256+
| `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. |
257+
| `authPersistance` | `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. |
258+
| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. |
259+
| `requestCredentials` | `string` | `"same-origin"` | _Optional:_ Controls cookie behavior for API requests. Options: `"omit"`, `"same-origin"`, or `"include"`. |
259260

260261
Example:
261262

@@ -267,6 +268,7 @@ Example:
267268
proxy: "https://cors.pan.dev", // Site-wide proxy (can be overridden per-spec in plugin config)
268269
authPersistance: "localStorage",
269270
requestTimeout: 60000, // 60 seconds
271+
requestCredentials: "omit", // Prevent cookies from being sent with requests
270272
},
271273
},
272274
}

‎demo/docs/intro.mdx‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -315,11 +315,12 @@ petstore: {
315315

316316
The `docusaurus-theme-openapi-docs` theme can be configured with the following options in `themeConfig.api`:
317317

318-
| Name | Type | Default | Description |
319-
| ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
320-
| `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. |
321-
| `authPersistance`| `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. |
322-
| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. |
318+
| Name | Type | Default | Description |
319+
| -------------------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
320+
| `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. |
321+
| `authPersistance` | `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. |
322+
| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. |
323+
| `requestCredentials` | `string` | `"same-origin"` | _Optional:_ Controls cookie behavior for API requests. Options: `"omit"`, `"same-origin"`, or `"include"`. |
323324

324325
Example:
325326

@@ -331,6 +332,7 @@ Example:
331332
proxy: "https://cors.pan.dev", // Site-wide proxy (can be overridden per-spec in plugin config)
332333
authPersistance: "localStorage",
333334
requestTimeout: 60000, // 60 seconds
335+
requestCredentials: "omit", // Prevent cookies from being sent with requests
334336
},
335337
},
336338
}

‎packages/docusaurus-plugin-openapi-docs/README.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -253,11 +253,12 @@ petstore: {
253253

254254
The `docusaurus-theme-openapi-docs` theme can be configured with the following options in `themeConfig.api`:
255255

256-
| Name | Type | Default | Description |
257-
| ----------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
258-
| `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. |
259-
| `authPersistance` | `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. |
260-
| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. |
256+
| Name | Type | Default | Description |
257+
| -------------------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
258+
| `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. |
259+
| `authPersistance` | `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. |
260+
| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. |
261+
| `requestCredentials` | `string` | `"same-origin"` | _Optional:_ Controls cookie behavior for API requests. Options: `"omit"`, `"same-origin"`, or `"include"`. |
261262

262263
Example:
263264

@@ -269,6 +270,7 @@ Example:
269270
proxy: "https://cors.pan.dev", // Site-wide proxy (can be overridden per-spec in plugin config)
270271
authPersistance: "localStorage",
271272
requestTimeout: 60000, // 60 seconds
273+
requestCredentials: "omit", // Prevent cookies from being sent with requests
272274
},
273275
},
274276
}

‎packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Request/index.tsx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ function Request({ item }: { item: ApiItem }) {
4343
const { siteConfig } = useDocusaurusContext();
4444
const themeConfig = siteConfig.themeConfig as ThemeConfig;
4545
const requestTimeout = themeConfig.api?.requestTimeout;
46+
const requestCredentials = themeConfig.api?.requestCredentials;
4647
// Frontmatter proxy (per-spec) takes precedence over theme config proxy (site-wide)
4748
const proxy = frontMatterProxy ?? themeConfig.api?.proxy;
4849

@@ -171,7 +172,8 @@ function Request({ item }: { item: ApiItem }) {
171172
postmanRequest,
172173
proxy,
173174
body,
174-
requestTimeout
175+
requestTimeout,
176+
requestCredentials
175177
);
176178
if (res.headers.get("content-type")?.includes("text/event-stream")) {
177179
await handleEventStream(res);

‎packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/Request/makeRequest.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,8 @@ async function makeRequest(
114114
request: sdk.Request,
115115
proxy: string | undefined,
116116
_body: Body,
117-
timeout: number = DEFAULT_REQUEST_TIMEOUT
117+
timeout: number = DEFAULT_REQUEST_TIMEOUT,
118+
credentials?: RequestCredentials
118119
) {
119120
const headers = request.toJSON().header;
120121

@@ -252,6 +253,7 @@ async function makeRequest(
252253
method: request.method,
253254
headers: myHeaders,
254255
body: myBody,
256+
...(credentials && { credentials }),
255257
};
256258

257259
let finalUrl = request.url.toString();

‎packages/docusaurus-theme-openapi-docs/src/types.d.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,13 @@ export interface ThemeConfig {
2727
authPersistence?: false | "sessionStorage" | "localStorage";
2828
/** Request timeout in milliseconds. Defaults to 30000 (30 seconds). */
2929
requestTimeout?: number;
30+
/**
31+
* Controls whether cookies and credentials are sent with API requests.
32+
* - `"omit"`: Never send cookies (useful when docs are on same domain as app)
33+
* - `"same-origin"`: Send cookies for same-origin requests (default browser behavior)
34+
* - `"include"`: Always send cookies, even for cross-origin requests
35+
*/
36+
requestCredentials?: "omit" | "same-origin" | "include";
3037
};
3138
}
3239

0 commit comments

Comments
 (0)