You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat(plugin): add externalJsonProps option (enabled by default) to improve build performance (#1279)
Add new externalJsonProps configuration option that extracts large JSON
props from MDX files into separate .json files loaded via require().
This bypasses MDX AST parsing for large JSON objects, significantly
improving build times for large OpenAPI specs.
The option is enabled by default due to the significant performance
benefits (25x faster builds in benchmarks). Users can opt-out by
setting externalJsonProps: false.
Changes:
- Add externalizeJsonProps.ts utility for JSON extraction
- Integrate with doc generation and cleanup flows
- Add TypeScript types and Joi validation (default: true)
- Update README with documentation and usage examples
- Update .gitignore to exclude generated JSON files
|`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. |
|`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. |
|`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. |
177
+
|`externalJsonProps`|`boolean`|`true`|_Optional:_ If set to `false`, disables externalization of large JSON props. By default, large JSON is written to external files for better build performance. |
Copy file name to clipboardExpand all lines: demo/docs/intro.mdx
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -221,6 +221,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
221
221
|`versions`|`object`|`null`|_Optional:_ Options for versioning configuration. See below for a list of supported options. |
222
222
|`markdownGenerators`|`object`|`null`|_Optional:_ Customize MDX content via generator functions. See below for a list of supported options. |
223
223
|`showSchemas`|`boolean`|`null`|_Optional:_ If set to `true`, generates standalone schema pages and adds them to the sidebar. |
224
+
|`externalJsonProps`|`boolean`|`true`|_Optional:_ If set to `false`, disables externalization of large JSON props. By default, large JSON is written to external files for better build performance. |
|`specPath`|`string`|`null`| Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
162
-
|`outputDir`|`string`|`null`| Desired output path for generated MDX and sidebar files. |
163
-
|`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. |
164
-
|`template`|`string`|`null`|_Optional:_ Customize MDX content with a desired template. |
165
-
|`infoTemplate`|`string`|`null`|_Optional:_ Customize MDX content for **info** pages only. |
166
-
|`tagTemplate`|`string`|`null`|_Optional:_ Customize MDX content for **tag** pages only. |
167
-
|`schemaTemplate`|`string`|`null`|_Optional:_ Customize MDX content for **schema** pages only. |
|`hideSendButton`|`boolean`|`null`|_Optional:_ If set to `true`, hides the “Send API Request” button in the API demo panel. |
170
-
|`showExtensions`|`boolean`|`null`|_Optional:_ If set to `true`, renders operation‑level vendor‑extensions in descriptions. |
171
-
|`maskCredentials`|`boolean`|`true`|_Optional:_ If set to `false`, disables credential masking in generated code snippets. By default, credentials are masked for security. |
172
-
|`sidebarOptions`|`object`|`null`|_Optional:_ Set of options for sidebar configuration. See below for a list of supported options. |
173
-
|`version`|`string`|`null`|_Optional:_ Version assigned to a single or micro‑spec API specified in `specPath`. |
174
-
|`label`|`string`|`null`|_Optional:_ Version label used when generating the version‑selector dropdown menu. |
175
-
|`baseUrl`|`string`|`null`|_Optional:_ Base URL for versioned docs in the version‑selector dropdown. |
176
-
|`versions`|`object`|`null`|_Optional:_ Options for versioning configuration. See below for a list of supported options. |
177
-
|`markdownGenerators`|`object`|`null`|_Optional:_ Customize MDX content via generator functions. See below for a list of supported options. |
178
-
|`showSchemas`|`boolean`|`null`|_Optional:_ If set to `true`, generates standalone schema pages and adds them to the sidebar. |
179
-
|`showInfoPage`|`boolean`|`true`|_Optional:_ If set to `false`, disables generation of the info page (overview page with API title and description). |
180
-
|`schemasOnly`|`boolean`|`false`|_Optional:_ If set to `true`, generates only schema pages (no API endpoint pages). Also available as `--schemas-only` CLI flag. |
|`specPath`|`string`|`null`| Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
162
+
|`outputDir`|`string`|`null`| Desired output path for generated MDX and sidebar files. |
163
+
|`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. |
164
+
|`template`|`string`|`null`|_Optional:_ Customize MDX content with a desired template. |
165
+
|`infoTemplate`|`string`|`null`|_Optional:_ Customize MDX content for **info** pages only. |
166
+
|`tagTemplate`|`string`|`null`|_Optional:_ Customize MDX content for **tag** pages only. |
167
+
|`schemaTemplate`|`string`|`null`|_Optional:_ Customize MDX content for **schema** pages only. |
|`hideSendButton`|`boolean`|`null`|_Optional:_ If set to `true`, hides the “Send API Request” button in the API demo panel. |
170
+
|`showExtensions`|`boolean`|`null`|_Optional:_ If set to `true`, renders operation‑level vendor‑extensions in descriptions. |
171
+
|`maskCredentials`|`boolean`|`true`|_Optional:_ If set to `false`, disables credential masking in generated code snippets. By default, credentials are masked for security. |
172
+
|`sidebarOptions`|`object`|`null`|_Optional:_ Set of options for sidebar configuration. See below for a list of supported options. |
173
+
|`version`|`string`|`null`|_Optional:_ Version assigned to a single or micro‑spec API specified in `specPath`. |
174
+
|`label`|`string`|`null`|_Optional:_ Version label used when generating the version‑selector dropdown menu. |
175
+
|`baseUrl`|`string`|`null`|_Optional:_ Base URL for versioned docs in the version‑selector dropdown. |
176
+
|`versions`|`object`|`null`|_Optional:_ Options for versioning configuration. See below for a list of supported options. |
177
+
|`markdownGenerators`|`object`|`null`|_Optional:_ Customize MDX content via generator functions. See below for a list of supported options. |
178
+
|`showSchemas`|`boolean`|`null`|_Optional:_ If set to `true`, generates standalone schema pages and adds them to the sidebar. |
179
+
|`showInfoPage`|`boolean`|`true`|_Optional:_ If set to `false`, disables generation of the info page (overview page with API title and description). |
180
+
|`schemasOnly`|`boolean`|`false`|_Optional:_ If set to `true`, generates only schema pages (no API endpoint pages). Also available as `--schemas-only` CLI flag. |
181
+
|`externalJsonProps`|`boolean`|`true`|_Optional:_ If set to `false`, disables externalization of large JSON props. By default, large JSON is written to external files for better build performance. |
181
182
182
183
### sidebarOptions
183
184
@@ -226,6 +227,28 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
|`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`|
228
229
230
+
### Performance Optimization
231
+
232
+
By default, `externalJsonProps` is enabled to optimize Docusaurus build times. This externalizes large JSON objects to separate files, significantly improving build performance for large OpenAPI specs.
233
+
234
+
**How it works:**
235
+
236
+
- With `externalJsonProps: true` (default): Large JSON props are written to separate `.json` files and loaded via `require()`. This bypasses MDX AST processing entirely, allowing the bundler to handle JSON more efficiently.
237
+
238
+
- With `externalJsonProps: false`: Large JSON objects (responses, request bodies, parameters) are embedded directly in the MDX. The MDX compiler must parse these into an AST and serialize them back, which can be slow for deeply nested schemas.
239
+
240
+
**When to disable:**
241
+
242
+
You may set `externalJsonProps: false` if you have custom tooling that depends on parsing the MDX files directly:
243
+
244
+
```typescript
245
+
petstore: {
246
+
specPath: "examples/petstore.yaml",
247
+
outputDir: "docs/petstore",
248
+
externalJsonProps: false, // Disable if needed for custom tooling
249
+
} satisfiesOpenApiPlugin.Options,
250
+
```
251
+
229
252
## Theme Configuration Options
230
253
231
254
The `docusaurus-theme-openapi-docs` theme can be configured with the following options in `themeConfig.api`:
0 commit comments