Skip to content

Commit bac31b9

Browse files
sserratasserrata
authored
Improve API request error handling and add support for customizing requestTimeout (#1267)
* feat(theme): improve error handling for API requests - Add custom RequestError class with typed error categories (timeout, network, cors, unknown) - Replace Promise.race timeout with AbortController for cleaner timeout handling - Add descriptive error messages for different failure scenarios - Add translation IDs for internationalization of error messages - Update Request component to display context-specific error messages * feat(theme): add configurable request timeout and site-wide proxy support - Increase default request timeout from 5s to 30s - Add requestTimeout option to themeConfig.api for site-wide configuration - Support proxy in themeConfig.api as site-wide default (per-spec plugin option takes precedence) - Update documentation in README.md, plugin README.md, and intro.mdx
1 parent 9a3a907 commit bac31b9

File tree

7 files changed

+285
-76
lines changed

7 files changed

+285
-76
lines changed

‎README.md‎

Lines changed: 44 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -155,25 +155,25 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
155155

156156
`config` can be configured with the following options:
157157

158-
| Name | Type | Default | Description |
159-
| -------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
160-
| `specPath` | `string` | `null` | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
161-
| `outputDir` | `string` | `null` | Desired output path for generated MDX and sidebar files. |
162-
| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. |
163-
| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. |
164-
| `infoTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **info** pages only. |
165-
| `tagTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **tag** pages only. |
166-
| `schemaTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **schema** pages only. |
167-
| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) |
168-
| `hideSendButton` | `boolean` | `null` | _Optional:_ If set to `true`, hides the “Send API Request” button in the API demo panel. |
169-
| `showExtensions` | `boolean` | `null` | _Optional:_ If set to `true`, renders operation‑level vendor‑extensions in descriptions. |
170-
| `sidebarOptions` | `object` | `null` | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options. |
171-
| `version` | `string` | `null` | _Optional:_ Version assigned to a single or micro‑spec API specified in `specPath`. |
172-
| `label` | `string` | `null` | _Optional:_ Version label used when generating the version‑selector dropdown menu. |
173-
| `baseUrl` | `string` | `null` | _Optional:_ Base URL for versioned docs in the version‑selector dropdown. |
174-
| `versions` | `object` | `null` | _Optional:_ Options for versioning configuration. See below for a list of supported options. |
175-
| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content via generator functions. See below for a list of supported options. |
176-
| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates standalone schema pages and adds them to the sidebar. |
158+
| Name | Type | Default | Description |
159+
| -------------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
160+
| `specPath` | `string` | `null` | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
161+
| `outputDir` | `string` | `null` | Desired output path for generated MDX and sidebar files. |
162+
| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. Overrides site-wide `themeConfig.api.proxy` if set. |
163+
| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. |
164+
| `infoTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **info** pages only. |
165+
| `tagTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **tag** pages only. |
166+
| `schemaTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **schema** pages only. |
167+
| `downloadUrl` | `string` | `null` | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc) |
168+
| `hideSendButton` | `boolean` | `null` | _Optional:_ If set to `true`, hides the “Send API Request” button in the API demo panel. |
169+
| `showExtensions` | `boolean` | `null` | _Optional:_ If set to `true`, renders operation‑level vendor‑extensions in descriptions. |
170+
| `sidebarOptions` | `object` | `null` | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options. |
171+
| `version` | `string` | `null` | _Optional:_ Version assigned to a single or micro‑spec API specified in `specPath`. |
172+
| `label` | `string` | `null` | _Optional:_ Version label used when generating the version‑selector dropdown menu. |
173+
| `baseUrl` | `string` | `null` | _Optional:_ Base URL for versioned docs in the version‑selector dropdown. |
174+
| `versions` | `object` | `null` | _Optional:_ Options for versioning configuration. See below for a list of supported options. |
175+
| `markdownGenerators` | `object` | `null` | _Optional:_ Customize MDX content via generator functions. See below for a list of supported options. |
176+
| `showSchemas` | `boolean` | `null` | _Optional:_ If set to `true`, generates standalone schema pages and adds them to the sidebar. |
177177

178178
### sidebarOptions
179179

@@ -221,6 +221,31 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
221221
| --------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
222222
| `createDocItem` | `function` | `null` | Optional: Returns a `SidebarItemDoc` object containing metadata for a sidebar item.<br/><br/>**Function type:** `(item: ApiPageMetadata \| SchemaPageMetadata, context: { sidebarOptions: SidebarOptions; basePath: string }) => SidebarItemDoc` |
223223

224+
## Theme Configuration Options
225+
226+
The `docusaurus-theme-openapi-docs` theme can be configured with the following options in `themeConfig.api`:
227+
228+
| Name | Type | Default | Description |
229+
| ----------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
230+
| `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. |
231+
| `authPersistance` | `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. |
232+
| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. |
233+
234+
Example:
235+
236+
```typescript
237+
// docusaurus.config.ts
238+
{
239+
themeConfig: {
240+
api: {
241+
proxy: "https://cors.pan.dev", // Site-wide proxy (can be overridden per-spec in plugin config)
242+
authPersistance: "localStorage",
243+
requestTimeout: 60000, // 60 seconds
244+
},
245+
},
246+
}
247+
```
248+
224249
## CLI Usage
225250

226251
```bash

‎demo/docs/intro.mdx‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -206,7 +206,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
206206
| -------------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
207207
| `specPath` | `string` | `null` | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
208208
| `outputDir` | `string` | `null` | Desired output path for generated MDX and sidebar files. |
209-
| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. |
209+
| `proxy` | `string` | `null` | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser. Overrides site-wide `themeConfig.api.proxy` if set. |
210210
| `template` | `string` | `null` | _Optional:_ Customize MDX content with a desired template. |
211211
| `infoTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **info** pages only. |
212212
| `tagTemplate` | `string` | `null` | _Optional:_ Customize MDX content for **tag** pages only. |
@@ -285,6 +285,31 @@ petstore31: {
285285
| --------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
286286
| `createDocItem` | `function` | `null` | Optional: Returns a `SidebarItemDoc` object containing metadata for a sidebar item.<br/><br/>**Function type:** `(item: ApiPageMetadata \| SchemaPageMetadata, context: { sidebarOptions: SidebarOptions; basePath: string }) => SidebarItemDoc` |
287287

288+
## Theme Configuration Options
289+
290+
The `docusaurus-theme-openapi-docs` theme can be configured with the following options in `themeConfig.api`:
291+
292+
| Name | Type | Default | Description |
293+
| ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
294+
| `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. |
295+
| `authPersistance`| `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. |
296+
| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. |
297+
298+
Example:
299+
300+
```typescript
301+
// docusaurus.config.ts
302+
{
303+
themeConfig: {
304+
api: {
305+
proxy: "https://cors.pan.dev", // Site-wide proxy (can be overridden per-spec in plugin config)
306+
authPersistance: "localStorage",
307+
requestTimeout: 60000, // 60 seconds
308+
},
309+
},
310+
}
311+
```
312+
288313
## CLI Usage
289314

290315
After you've installed and configured the plugin and theme, the CLI can be used to `generate` and `clean` API docs.

0 commit comments

Comments
 (0)