Skip to content

Commit 5d386e3

Browse files
sserrataclaude
sserrata
and
claude
committed
docs: document themeConfig.api.schemaExpansion option
Adds documentation for the new schemaExpansion theme option (introduced in #1449) to intro.mdx and both READMEs, covering the nested enabled, default, max, and persist fields plus an example config. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent 0b3d488 commit 5d386e3

3 files changed

Lines changed: 69 additions & 12 deletions

File tree

‎README.md‎

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -252,12 +252,13 @@ petstore: {
252252

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

255-
| Name | Type | Default | Description |
256-
| -------------------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
257-
| `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. |
258-
| `authPersistance` | `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. |
259-
| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. |
260-
| `requestCredentials` | `string` | `"same-origin"` | _Optional:_ Controls cookie behavior for API requests. Options: `"omit"`, `"same-origin"`, or `"include"`. |
255+
| Name | Type | Default | Description |
256+
| -------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
257+
| `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. |
258+
| `authPersistance` | `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. |
259+
| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. |
260+
| `requestCredentials` | `string` | `"same-origin"` | _Optional:_ Controls cookie behavior for API requests. Options: `"omit"`, `"same-origin"`, or `"include"`. |
261+
| `schemaExpansion` | `object` | `null` | _Optional:_ Controls the default expansion depth of nested request/response schema trees and (optionally) renders an inline depth control. See [`schemaExpansion`](#schemaexpansion) below. |
261262

262263
Example:
263264

@@ -270,11 +271,29 @@ Example:
270271
authPersistance: "localStorage",
271272
requestTimeout: 60000, // 60 seconds
272273
requestCredentials: "omit", // Prevent cookies from being sent with requests
274+
schemaExpansion: {
275+
enabled: true, // render the inline depth control next to each schema header
276+
default: 1, // auto-expand the first level on page load
277+
max: 4, // highest numeric depth offered by the control
278+
},
273279
},
274280
},
275281
}
276282
```
277283

284+
### schemaExpansion
285+
286+
Inspired by Redoc's `schemaExpansionLevel`, `schemaExpansion` configures how deeply nested schema trees auto-expand and whether readers can change the depth at view time.
287+
288+
| Name | Type | Default | Description |
289+
| --------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
290+
| `enabled` | `boolean` | `false` | Render an interactive depth control next to each schema header so readers can change the expansion depth at view time. |
291+
| `default` | `number \| "all"` | `0` | Initial expansion depth applied on every page load. Use `"all"` to expand everything. Applies whether or not `enabled` is `true`. |
292+
| `max` | `number` | `4` | Highest numeric depth offered by the UI control. Ignored when `enabled` is `false`. |
293+
| `persist` | `boolean` | `true` | Persist the reader's selected depth in `localStorage`. Only meaningful when `enabled` is `true`; persistence is implicitly off when the control is hidden. |
294+
295+
You can set just `{ default: 1 }` to auto-expand the first level on every page load without rendering the depth control. When `schemaExpansion` is unset entirely, behavior is unchanged from prior releases (all schemas collapsed by default).
296+
278297
## Supported Vendor Extensions
279298

280299
The plugin extracts a number of vendor extensions from the OpenAPI spec to enrich the generated docs. The theme renders some of these values as part of the UI.

‎demo/docs/intro.mdx‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -319,6 +319,7 @@ The `docusaurus-theme-openapi-docs` theme can be configured with the following o
319319
| `authPersistance` | `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. |
320320
| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. |
321321
| `requestCredentials` | `string` | `"same-origin"` | _Optional:_ Controls cookie behavior for API requests. Options: `"omit"`, `"same-origin"`, or `"include"`. |
322+
| `schemaExpansion` | `object` | `null` | _Optional:_ Controls the default expansion depth of nested request/response schema trees and (optionally) renders an inline depth control. See [`schemaExpansion`](#schemaexpansion) below. |
322323

323324
Example:
324325

@@ -331,11 +332,29 @@ Example:
331332
authPersistance: "localStorage",
332333
requestTimeout: 60000, // 60 seconds
333334
requestCredentials: "omit", // Prevent cookies from being sent with requests
335+
schemaExpansion: {
336+
enabled: true, // render the inline depth control next to each schema header
337+
default: 1, // auto-expand the first level on page load
338+
max: 4, // highest numeric depth offered by the control
339+
},
334340
},
335341
},
336342
}
337343
```
338344

345+
### schemaExpansion
346+
347+
Inspired by Redoc's `schemaExpansionLevel`, `schemaExpansion` configures how deeply nested schema trees auto-expand and whether readers can change the depth at view time.
348+
349+
| Name | Type | Default | Description |
350+
| --------- | ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
351+
| `enabled` | `boolean` | `false` | Render an interactive depth control next to each schema header so readers can change the expansion depth at view time. |
352+
| `default` | `number \| "all"` | `0` | Initial expansion depth applied on every page load. Use `"all"` to expand everything. Applies whether or not `enabled` is `true`. |
353+
| `max` | `number` | `4` | Highest numeric depth offered by the UI control. Ignored when `enabled` is `false`. |
354+
| `persist` | `boolean` | `true` | Persist the reader's selected depth in `localStorage`. Only meaningful when `enabled` is `true`; persistence is implicitly off when the control is hidden. |
355+
356+
You can set just `{ default: 1 }` to auto-expand the first level on every page load without rendering the depth control. When `schemaExpansion` is unset entirely, behavior is unchanged from prior releases (all schemas collapsed by default).
357+
339358
## CLI Usage
340359

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

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

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -252,12 +252,13 @@ petstore: {
252252

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

255-
| Name | Type | Default | Description |
256-
| -------------------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
257-
| `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. |
258-
| `authPersistance` | `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. |
259-
| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. |
260-
| `requestCredentials` | `string` | `"same-origin"` | _Optional:_ Controls cookie behavior for API requests. Options: `"omit"`, `"same-origin"`, or `"include"`. |
255+
| Name | Type | Default | Description |
256+
| -------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
257+
| `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. |
258+
| `authPersistance` | `string` | `null` | _Optional:_ Determines how auth credentials are persisted. Options: `"localStorage"`, `"sessionStorage"`, or `false` to disable. |
259+
| `requestTimeout` | `number` | `30000` | _Optional:_ Request timeout in milliseconds for API requests made from the browser. Defaults to 30 seconds. |
260+
| `requestCredentials` | `string` | `"same-origin"` | _Optional:_ Controls cookie behavior for API requests. Options: `"omit"`, `"same-origin"`, or `"include"`. |
261+
| `schemaExpansion` | `object` | `null` | _Optional:_ Controls the default expansion depth of nested request/response schema trees and (optionally) renders an inline depth control. See [`schemaExpansion`](#schemaexpansion) below. |
261262

262263
Example:
263264

@@ -270,11 +271,29 @@ Example:
270271
authPersistance: "localStorage",
271272
requestTimeout: 60000, // 60 seconds
272273
requestCredentials: "omit", // Prevent cookies from being sent with requests
274+
schemaExpansion: {
275+
enabled: true, // render the inline depth control next to each schema header
276+
default: 1, // auto-expand the first level on page load
277+
max: 4, // highest numeric depth offered by the control
278+
},
273279
},
274280
},
275281
}
276282
```
277283

284+
### schemaExpansion
285+
286+
Inspired by Redoc's `schemaExpansionLevel`, `schemaExpansion` configures how deeply nested schema trees auto-expand and whether readers can change the depth at view time.
287+
288+
| Name | Type | Default | Description |
289+
| --------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
290+
| `enabled` | `boolean` | `false` | Render an interactive depth control next to each schema header so readers can change the expansion depth at view time. |
291+
| `default` | `number \| "all"` | `0` | Initial expansion depth applied on every page load. Use `"all"` to expand everything. Applies whether or not `enabled` is `true`. |
292+
| `max` | `number` | `4` | Highest numeric depth offered by the UI control. Ignored when `enabled` is `false`. |
293+
| `persist` | `boolean` | `true` | Persist the reader's selected depth in `localStorage`. Only meaningful when `enabled` is `true`; persistence is implicitly off when the control is hidden. |
294+
295+
You can set just `{ default: 1 }` to auto-expand the first level on every page load without rendering the depth control. When `schemaExpansion` is unset entirely, behavior is unchanged from prior releases (all schemas collapsed by default).
296+
278297
## Supported Vendor Extensions
279298

280299
The plugin extracts a number of vendor extensions from the OpenAPI spec to enrich the generated docs. The theme renders some of these values as part of the UI.

0 commit comments

Comments
 (0)