docusaurus-plugin-openapi-docs 4.5.1 → 4.7.0

package/README.md

@@ -11,7 +11,7 @@ OpenAPI plugin for generating API reference docs in Docusaurus v3.
 <img src="https://img.shields.io/badge/dynamic/json?style=for-the-badge&logo=meta&color=blueviolet&label=Docusaurus&query=dependencies%5B%22%40docusaurus%2Fcore%22%5D&url=https%3A%2F%2Fraw.githubusercontent.com%2FPaloAltoNetworks%2Fdocusaurus-openapi-docs%2Fmain%2Fdemo%2Fpackage.json" />
 <br/><br/>
 
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/HEAD/LICENSE) [![npm latest package](https://img.shields.io/npm/v/docusaurus-plugin-openapi-docs/latest.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [![npm downloads](https://img.shields.io/npm/dm/docusaurus-plugin-openapi-docs.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [![npm canary package](https://img.shields.io/npm/v/docusaurus-plugin-openapi-docs/canary.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [![npm beta package](https://img.shields.io/npm/v/docusaurus-plugin-openapi-docs/beta.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/HEAD/LICENSE) [![npm latest package](https://img.shields.io/npm/v/docusaurus-plugin-openapi-docs/latest.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [![npm downloads](https://img.shields.io/npm/dm/docusaurus-plugin-openapi-docs.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs) [![npm canary package](https://img.shields.io/npm/v/docusaurus-plugin-openapi-docs/canary.svg)](https://www.npmjs.com/package/docusaurus-plugin-openapi-docs)
 <br/>
 [![build](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/actions/workflows/validate.yaml/badge.svg)](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/actions/workflows/validate.yaml) [![prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier) [![Cypress.io](https://img.shields.io/badge/tested%20with-Cypress-04C38E.svg)](https://www.cypress.io/) [![jest](https://jestjs.io/img/jest-badge.svg)](https://github.com/facebook/jest) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/blob/HEAD/CONTRIBUTING.md#pull-requests)
 <br />
@@ -41,7 +41,7 @@ Key Features:
 
 | Docusaurus OpenAPI Docs | Docusaurus      |
 | ----------------------- | --------------- |
-| 4.0.x (current)         | `3.5.0 - 3.8.1` |
+| 4.x.x (current)         | `3.5.0 - 3.9.2` |
 | 3.0.x (end-of-support)  | `3.0.1 - 3.4.0` |
 | 2.2.3 (legacy)          | `2.4.1 - 2.4.3` |
 | 1.7.3 (end-of-support)  | `2.0.1 - 2.2.0` |
@@ -51,7 +51,7 @@ Key Features:
 Run the following to bootstrap a Docusaurus v3 site (classic theme) with `docusaurus-openapi-docs`:
 
 ```bash
-npx create-docusaurus@3.8.1 my-website --package-manager yarn
+npx create-docusaurus@3.9.2 my-website --package-manager yarn
 ```
 
 > When prompted to select a template choose `Git repository`.
@@ -127,6 +127,7 @@ import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs";
           petstore: {
             specPath: "examples/petstore.yaml",
             outputDir: "docs/petstore",
+            maskCredentials: false, // Disable credential masking in code snippets
             sidebarOptions: {
               groupPathsBy: "tag",
             },
@@ -155,25 +156,29 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
 
 `config` can be configured with the following options:
 
-| Name                 | Type      | Default | Description                                                                                                                 |
-| -------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `specPath`           | `string`  | `null`  | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files. |
-| `outputDir`          | `string`  | `null`  | Desired output path for generated MDX and sidebar files.                                                                    |
-| `proxy`              | `string`  | `null`  | _Optional:_ Proxy URL to prepend to base URL when performing API requests from browser.                                     |
-| `template`           | `string`  | `null`  | _Optional:_ Customize MDX content with a desired template.                                                                  |
-| `infoTemplate`       | `string`  | `null`  | _Optional:_ Customize MDX content for **info** pages only.                                                                  |
-| `tagTemplate`        | `string`  | `null`  | _Optional:_ Customize MDX content for **tag** pages only.                                                                   |
-| `schemaTemplate`     | `string`  | `null`  | _Optional:_ Customize MDX content for **schema** pages only.                                                                |
-| `downloadUrl`        | `string`  | `null`  | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc)                             |
-| `hideSendButton`     | `boolean` | `null`  | _Optional:_ If set to `true`, hides the “Send API Request” button in the API demo panel.                                    |
-| `showExtensions`     | `boolean` | `null`  | _Optional:_ If set to `true`, renders operation‑level vendor‑extensions in descriptions.                                    |
-| `sidebarOptions`     | `object`  | `null`  | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options.                            |
-| `version`            | `string`  | `null`  | _Optional:_ Version assigned to a single or micro‑spec API specified in `specPath`.                                         |
-| `label`              | `string`  | `null`  | _Optional:_ Version label used when generating the version‑selector dropdown menu.                                          |
-| `baseUrl`            | `string`  | `null`  | _Optional:_ Base URL for versioned docs in the version‑selector dropdown.                                                   |
-| `versions`           | `object`  | `null`  | _Optional:_ Options for versioning configuration. See below for a list of supported options.                                |
-| `markdownGenerators` | `object`  | `null`  | _Optional:_ Customize MDX content via generator functions. See below for a list of supported options.                       |
-| `showSchemas`        | `boolean` | `null`  | _Optional:_ If set to `true`, generates standalone schema pages and adds them to the sidebar.                               |
+| Name                 | Type      | Default | Description                                                                                                                                                    |
+| -------------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `specPath`           | `string`  | `null`  | Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files.                                    |
+| `outputDir`          | `string`  | `null`  | Desired output path for generated MDX and sidebar files.                                                                                                       |
+| `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.                    |
+| `template`           | `string`  | `null`  | _Optional:_ Customize MDX content with a desired template.                                                                                                     |
+| `infoTemplate`       | `string`  | `null`  | _Optional:_ Customize MDX content for **info** pages only.                                                                                                     |
+| `tagTemplate`        | `string`  | `null`  | _Optional:_ Customize MDX content for **tag** pages only.                                                                                                      |
+| `schemaTemplate`     | `string`  | `null`  | _Optional:_ Customize MDX content for **schema** pages only.                                                                                                   |
+| `downloadUrl`        | `string`  | `null`  | _Optional:_ Designated URL for downloading OpenAPI specification. (requires `info` section/doc)                                                                |
+| `hideSendButton`     | `boolean` | `null`  | _Optional:_ If set to `true`, hides the “Send API Request” button in the API demo panel.                                                                       |
+| `showExtensions`     | `boolean` | `null`  | _Optional:_ If set to `true`, renders operation‑level vendor‑extensions in descriptions.                                                                       |
+| `maskCredentials`    | `boolean` | `true`  | _Optional:_ If set to `false`, disables credential masking in generated code snippets. By default, credentials are masked for security.                        |
+| `sidebarOptions`     | `object`  | `null`  | _Optional:_ Set of options for sidebar configuration. See below for a list of supported options.                                                               |
+| `version`            | `string`  | `null`  | _Optional:_ Version assigned to a single or micro‑spec API specified in `specPath`.                                                                            |
+| `label`              | `string`  | `null`  | _Optional:_ Version label used when generating the version‑selector dropdown menu.                                                                             |
+| `baseUrl`            | `string`  | `null`  | _Optional:_ Base URL for versioned docs in the version‑selector dropdown.                                                                                      |
+| `versions`           | `object`  | `null`  | _Optional:_ Options for versioning configuration. See below for a list of supported options.                                                                   |
+| `markdownGenerators` | `object`  | `null`  | _Optional:_ Customize MDX content via generator functions. See below for a list of supported options.                                                          |
+| `showSchemas`        | `boolean` | `null`  | _Optional:_ If set to `true`, generates standalone schema pages and adds them to the sidebar.                                                                  |
+| `showInfoPage`       | `boolean` | `true`  | _Optional:_ If set to `false`, disables generation of the info page (overview page with API title and description).                                            |
+| `schemasOnly`        | `boolean` | `false` | _Optional:_ If set to `true`, generates only schema pages (no API endpoint pages). Also available as `--schemas-only` CLI flag.                                |
+| `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. |
 
 ### sidebarOptions
 
@@ -222,6 +227,71 @@ 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` |
 
+### Performance Optimization
+
+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.
+
+**How it works:**
+
+- 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.
+
+- 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.
+
+**When to disable:**
+
+You may set `externalJsonProps: false` if you have custom tooling that depends on parsing the MDX files directly:
+
+```typescript
+petstore: {
+  specPath: "examples/petstore.yaml",
+  outputDir: "docs/petstore",
+  externalJsonProps: false, // Disable if needed for custom tooling
+} satisfies OpenApiPlugin.Options,
+```
+
+## Theme Configuration Options
+
+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.                        |
+
+Example:
+
+```typescript
+// docusaurus.config.ts
+{
+  themeConfig: {
+    api: {
+      proxy: "https://cors.pan.dev",  // Site-wide proxy (can be overridden per-spec in plugin config)
+      authPersistance: "localStorage",
+      requestTimeout: 60000, // 60 seconds
+    },
+  },
+}
+```
+
+## Supported Vendor Extensions
+
+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.
+
+| Extension                                  | Purpose                                                               |
+| ------------------------------------------ | --------------------------------------------------------------------- |
+| `x-codeSamples`                            | Operation level code snippets displayed in the API Explorer.          |
+| `x-tagGroups`                              | Groups tags in the sidebar navigation.                                |
+| `x-tags`                                   | Assigns tags to schema objects so they appear with tagged operations. |
+| `x-position`                               | Controls ordering of items in the sidebar.                            |
+| `x-logo` / `x-dark-logo`                   | Provides logos for light and dark themes on the intro page.           |
+| `x-deprecated-description`                 | Custom text shown for deprecated operations.                          |
+| `x-webhooks`                               | Defines webhook events.                                               |
+| `x-displayName`                            | Overrides tag display names.                                          |
+| `x-enumDescription` / `x-enumDescriptions` | Documents enum values.                                                |
+
+Other ReDoc specific extensions such as `x-circular-ref`, `x-code-samples` (deprecated), `x-examples`, `x-ignoredHeaderParameters`, `x-nullable`, `x-servers`, `x-traitTag`, `x-additionalPropertiesName`, and `x-explicitMappingOnly` are ignored when extracting custom data.
+
 ## CLI Usage
 
 ```bash
@@ -283,6 +353,16 @@ yarn docusaurus gen-api-docs all --all-versions
 
 > This will generate API docs for all versions of all the OpenAPI specification (OAS) files referenced in your `docusaurus-plugin-openapi-docs` config.
 
+To generate only schema MDX files—without updating the sidebar or requiring `showSchemas` in your plugin config—use the `--schemas-only` flag:
+
+```bash
+yarn docusaurus gen-api-docs petstore --schemas-only
+```
+
+> This command writes the schema pages to the configured output directory while leaving other generated docs untouched.
+
+The `--schemas-only` flag is also available for `gen-api-docs:version`.
+
 ### Cleaning API Docs
 
 To clean/remove all API Docs, run the following command from the root directory of your project:
@@ -315,6 +395,14 @@ yarn docusaurus clean-api-docs all --all-versions
 
 > This will clean API docs for all versions of all the OpenAPI specification (OAS) files referenced in your `docusaurus-plugin-openapi-docs` config.
 
+To clean only schema docs while leaving API, info, and tag docs untouched, use the `--schemas-only` flag:
+
+```bash
+yarn docusaurus clean-api-docs petstore --schemas-only
+```
+
+> The `--schemas-only` flag is also available for `clean-api-docs:version`.
+
 ### Versioning OpenAPI docs
 
 To generate _all_ versioned OpenAPI docs, run the following command from the root directory of your project:

package/lib/index.js

@@ -20,6 +20,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const json5_1 = __importDefault(require("json5"));
 const mustache_1 = require("mustache");
 const markdown_1 = require("./markdown");
+const utils_2 = require("./markdown/utils");
 const openapi_1 = require("./openapi");
 const options_1 = require("./options");
 const sidebars_1 = __importDefault(require("./sidebars"));
@@ -78,7 +79,8 @@ function pluginOpenAPIDocs(context, options) {
     let docPath = docData ? (docData.path ? docData.path : "docs") : undefined;
     async function generateApiDocs(options, pluginId) {
         var _a, _b, _c, _d;
-        let { specPath, outputDir, template, infoTemplate, tagTemplate, schemaTemplate, markdownGenerators, downloadUrl, sidebarOptions, disableCompression, } = options;
+        let { specPath, outputDir, template, infoTemplate, tagTemplate, schemaTemplate, markdownGenerators, downloadUrl, sidebarOptions, schemasOnly, disableCompression, } = options;
+        const isSchemasOnly = schemasOnly === true;
         // Remove trailing slash before proceeding
         outputDir = outputDir.replace(/\/$/, "");
         // Override docPath if pluginId provided
@@ -103,7 +105,7 @@ function pluginOpenAPIDocs(context, options) {
                 }
             }
             // TODO: figure out better way to set default
-            if (Object.keys(sidebarOptions !== null && sidebarOptions !== void 0 ? sidebarOptions : {}).length > 0) {
+            if (!isSchemasOnly && Object.keys(sidebarOptions !== null && sidebarOptions !== void 0 ? sidebarOptions : {}).length > 0) {
                 const sidebarSlice = (0, sidebars_1.default)(sidebarOptions, options, loadedApi, tags, docPath, tagGroups);
                 let sidebarSliceTemplate = `import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";\n\n`;
                 sidebarSliceTemplate += `const sidebar: SidebarsConfig = {{{slice}}};\n\n`;
@@ -159,6 +161,9 @@ hide_send_button: true
 {{#frontMatter.show_extensions}}
 show_extensions: true
 {{/frontMatter.show_extensions}}
+{{#frontMatter.mask_credentials_disabled}}
+mask_credentials: false
+{{/frontMatter.mask_credentials_disabled}}
 ---
 
 {{{markdown}}}
@@ -230,11 +235,24 @@ custom_edit_url: null
                 schema: schemaPageGenerator,
             };
             loadedApi.map(async (item) => {
+                var _a, _b;
                 if (downloadUrl) {
                     item.downloadUrl = downloadUrl;
                 }
-                const markdown = pageGeneratorByType[item.type](item);
-                item.markdown = markdown;
+                // Generate markdown, with externalization for API and schema pages
+                let externalFiles = [];
+                if (options.externalJsonProps &&
+                    (item.type === "api" || item.type === "schema")) {
+                    const result = (0, utils_2.runWithExternalization)(item.id, () => pageGeneratorByType[item.type](item));
+                    item.markdown = result.result;
+                    externalFiles = result.files;
+                }
+                else {
+                    item.markdown = pageGeneratorByType[item.type](item);
+                }
+                if (isSchemasOnly && item.type !== "schema") {
+                    return;
+                }
                 if (item.type === "api") {
                     // opportunity to compress JSON
                     // const serialize = (o: any) => {
@@ -250,9 +268,14 @@ custom_edit_url: null
                             .toString("base64"));
                     let infoBasePath = `${outputDir}/${item.infoId}`;
                     if (docRouteBasePath) {
-                        infoBasePath = `${docRouteBasePath}/${outputDir
-                            .split(docPath)[1]
-                            .replace(/^\/+/g, "")}/${item.infoId}`.replace(/^\/+/g, "");
+                        // Safely extract path segment, handling cases where docPath may not be in outputDir
+                        const outputSegment = docPath && outputDir.includes(docPath)
+                            ? ((_b = (_a = outputDir.split(docPath)[1]) === null || _a === void 0 ? void 0 : _a.replace(/^\/+/g, "")) !== null && _b !== void 0 ? _b : "")
+                            : outputDir
+                                .slice(outputDir.indexOf("/", 1))
+                                .replace(/^\/+/g, "");
+                        infoBasePath =
+                            `${docRouteBasePath}/${outputSegment}/${item.infoId}`.replace(/^\/+/g, "");
                     }
                     if (item.infoId)
                         item.infoPath = infoBasePath;
@@ -268,6 +291,14 @@ custom_edit_url: null
                             if (item.id.length === 0) {
                                 throw Error("Operation must have summary or operationId defined");
                             }
+                            // Write externalized JSON files
+                            for (const jsonFile of externalFiles) {
+                                const jsonPath = `${outputDir}/${jsonFile.filename}`;
+                                if (!fs_1.default.existsSync(jsonPath)) {
+                                    fs_1.default.writeFileSync(jsonPath, jsonFile.content, "utf8");
+                                    console.log(chalk_1.default.green(`Successfully created "${jsonPath}"`));
+                                }
+                            }
                             fs_1.default.writeFileSync(`${outputDir}/${item.id}.api.mdx`, view, "utf8");
                             console.log(chalk_1.default.green(`Successfully created "${outputDir}/${item.id}.api.mdx"`));
                         }
@@ -318,6 +349,14 @@ custom_edit_url: null
                             }
                             // eslint-disable-next-line testing-library/render-result-naming-convention
                             const schemaView = (0, mustache_1.render)(schemaMdTemplate, item);
+                            // Write externalized JSON files in schemas directory
+                            for (const jsonFile of externalFiles) {
+                                const jsonPath = `${outputDir}/schemas/${jsonFile.filename}`;
+                                if (!fs_1.default.existsSync(jsonPath)) {
+                                    fs_1.default.writeFileSync(jsonPath, jsonFile.content, "utf8");
+                                    console.log(chalk_1.default.green(`Successfully created "${jsonPath}"`));
+                                }
+                            }
                             fs_1.default.writeFileSync(`${outputDir}/schemas/${item.id}.schema.mdx`, schemaView, "utf8");
                             console.log(chalk_1.default.green(`Successfully created "${outputDir}/${item.id}.schema.mdx"`));
                         }
@@ -335,25 +374,50 @@ custom_edit_url: null
             throw e;
         }
     }
-    async function cleanApiDocs(options) {
+    async function cleanApiDocs(options, schemasOnly = false) {
         const { outputDir } = options;
         const apiDir = (0, utils_1.posixPath)(path_1.default.join(siteDir, outputDir));
-        const apiMdxFiles = await (0, utils_1.Globby)(["*.api.mdx", "*.info.mdx", "*.tag.mdx"], {
-            cwd: path_1.default.resolve(apiDir),
-            deep: 1,
-        });
-        const sidebarFile = await (0, utils_1.Globby)(["sidebar.js", "sidebar.ts"], {
-            cwd: path_1.default.resolve(apiDir),
-            deep: 1,
-        });
-        apiMdxFiles.map((mdx) => fs_1.default.unlink(`${apiDir}/${mdx}`, (err) => {
-            if (err) {
-                console.error(chalk_1.default.red(`Cleanup failed for "${apiDir}/${mdx}"`), chalk_1.default.yellow(err));
-            }
-            else {
-                console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/${mdx}"`));
-            }
-        }));
+        // When schemasOnly is true, only clean the schemas directory
+        if (!schemasOnly) {
+            const apiMdxFiles = await (0, utils_1.Globby)(["*.api.mdx", "*.info.mdx", "*.tag.mdx"], {
+                cwd: path_1.default.resolve(apiDir),
+                deep: 1,
+            });
+            const sidebarFile = await (0, utils_1.Globby)(["sidebar.js", "sidebar.ts"], {
+                cwd: path_1.default.resolve(apiDir),
+                deep: 1,
+            });
+            // Clean up externalized JSON files
+            const jsonFiles = await (0, utils_1.Globby)(["*.json", "!versions.json"], {
+                cwd: path_1.default.resolve(apiDir),
+                deep: 1,
+            });
+            apiMdxFiles.map((mdx) => fs_1.default.unlink(`${apiDir}/${mdx}`, (err) => {
+                if (err) {
+                    console.error(chalk_1.default.red(`Cleanup failed for "${apiDir}/${mdx}"`), chalk_1.default.yellow(err));
+                }
+                else {
+                    console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/${mdx}"`));
+                }
+            }));
+            sidebarFile.map((sidebar) => fs_1.default.unlink(`${apiDir}/${sidebar}`, (err) => {
+                if (err) {
+                    console.error(chalk_1.default.red(`Cleanup failed for "${apiDir}/${sidebar}"`), chalk_1.default.yellow(err));
+                }
+                else {
+                    console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/${sidebar}"`));
+                }
+            }));
+            // Clean up externalized JSON files
+            jsonFiles.map((jsonFile) => fs_1.default.unlink(`${apiDir}/${jsonFile}`, (err) => {
+                if (err) {
+                    console.error(chalk_1.default.red(`Cleanup failed for "${apiDir}/${jsonFile}"`), chalk_1.default.yellow(err));
+                }
+                else {
+                    console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/${jsonFile}"`));
+                }
+            }));
+        }
         try {
             fs_1.default.rmSync(`${apiDir}/schemas`, { recursive: true });
             console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/schemas"`));
@@ -363,14 +427,6 @@ custom_edit_url: null
                 console.error(chalk_1.default.red(`Cleanup failed for "${apiDir}/schemas"`), chalk_1.default.yellow(err));
             }
         }
-        sidebarFile.map((sidebar) => fs_1.default.unlink(`${apiDir}/${sidebar}`, (err) => {
-            if (err) {
-                console.error(chalk_1.default.red(`Cleanup failed for "${apiDir}/${sidebar}"`), chalk_1.default.yellow(err));
-            }
-            else {
-                console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/${sidebar}"`));
-            }
-        }));
     }
     async function generateVersions(versions, outputDir) {
         let versionsArray = [];
@@ -442,19 +498,21 @@ custom_edit_url: null
             });
         }
     }
-    async function cleanAllVersions(options) {
+    async function cleanAllVersions(options, schemasOnly = false) {
         const parentOptions = Object.assign({}, options);
         const { versions } = parentOptions;
         delete parentOptions.versions;
         if (versions != null && Object.keys(versions).length > 0) {
-            await cleanVersions(parentOptions.outputDir);
+            if (!schemasOnly) {
+                await cleanVersions(parentOptions.outputDir);
+            }
             Object.keys(versions).forEach(async (key) => {
                 const versionOptions = versions[key];
                 const mergedOptions = {
                     ...parentOptions,
                     ...versionOptions,
                 };
-                await cleanApiDocs(mergedOptions);
+                await cleanApiDocs(mergedOptions, schemasOnly);
             });
         }
     }
@@ -468,11 +526,13 @@ custom_edit_url: null
                 .arguments("<id>")
                 .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
                 .option("--all-versions", "Generate all versions.")
+                .option("--schemas-only", "Generate only schema docs.")
                 .action(async (id, instance) => {
                 var _a;
                 const options = instance.opts();
                 const pluginId = options.pluginId;
                 const allVersions = options.allVersions;
+                const schemasOnly = options.schemasOnly;
                 const pluginInstances = getPluginInstances(plugins);
                 let targetConfig;
                 let targetDocsPluginId;
@@ -494,15 +554,17 @@ custom_edit_url: null
                     }
                     targetConfig = config;
                 }
+                const withSchemaOverride = (apiOptions) => schemasOnly ? { ...apiOptions, schemasOnly: true } : apiOptions;
                 if (id === "all") {
                     if (targetConfig[id]) {
                         console.error(chalk_1.default.red("Can't use id 'all' for OpenAPI docs configuration key."));
                     }
                     else {
                         Object.keys(targetConfig).forEach(async function (key) {
-                            await generateApiDocs(targetConfig[key], targetDocsPluginId);
+                            const apiOptions = withSchemaOverride(targetConfig[key]);
+                            await generateApiDocs(apiOptions, targetDocsPluginId);
                             if (allVersions) {
-                                await generateAllVersions(targetConfig[key], targetDocsPluginId);
+                                await generateAllVersions(apiOptions, targetDocsPluginId);
                             }
                         });
                     }
@@ -511,9 +573,10 @@ custom_edit_url: null
                     console.error(chalk_1.default.red(`ID '${id}' does not exist in OpenAPI docs config.`));
                 }
                 else {
-                    await generateApiDocs(targetConfig[id], targetDocsPluginId);
+                    const apiOptions = withSchemaOverride(targetConfig[id]);
+                    await generateApiDocs(apiOptions, targetDocsPluginId);
                     if (allVersions) {
-                        await generateAllVersions(targetConfig[id], targetDocsPluginId);
+                        await generateAllVersions(apiOptions, targetDocsPluginId);
                     }
                 }
             });
@@ -523,10 +586,12 @@ custom_edit_url: null
                 .usage("<id:version>")
                 .arguments("<id:version>")
                 .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
+                .option("--schemas-only", "Generate only schema docs.")
                 .action(async (id, instance) => {
                 var _a;
                 const options = instance.opts();
                 const pluginId = options.pluginId;
+                const schemasOnly = options.schemasOnly;
                 const pluginInstances = getPluginInstances(plugins);
                 let targetConfig;
                 let targetDocsPluginId;
@@ -550,6 +615,7 @@ custom_edit_url: null
                 }
                 const [parentId, versionId] = id.split(":");
                 const parentConfig = Object.assign({}, targetConfig[parentId]);
+                const withSchemaOverride = (apiOptions) => schemasOnly ? { ...apiOptions, schemasOnly: true } : apiOptions;
                 const version = parentConfig.version;
                 const label = parentConfig.label;
                 const baseUrl = parentConfig.baseUrl;
@@ -572,10 +638,10 @@ custom_edit_url: null
                         await generateVersions(mergedVersions, parentConfig.outputDir);
                         Object.keys(versions).forEach(async (key) => {
                             const versionConfig = versions[key];
-                            const mergedConfig = {
+                            const mergedConfig = withSchemaOverride({
                                 ...parentConfig,
                                 ...versionConfig,
-                            };
+                            });
                             await generateApiDocs(mergedConfig, targetDocsPluginId);
                         });
                     }
@@ -585,10 +651,10 @@ custom_edit_url: null
                 }
                 else {
                     const versionConfig = versions[versionId];
-                    const mergedConfig = {
+                    const mergedConfig = withSchemaOverride({
                         ...parentConfig,
                         ...versionConfig,
-                    };
+                    });
                     await generateVersions(mergedVersions, parentConfig.outputDir);
                     await generateApiDocs(mergedConfig, targetDocsPluginId);
                 }
@@ -600,11 +666,13 @@ custom_edit_url: null
                 .arguments("<id>")
                 .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
                 .option("--all-versions", "Clean all versions.")
+                .option("--schemas-only", "Clean only schema docs.")
                 .action(async (id, instance) => {
                 var _a;
                 const options = instance.opts();
                 const pluginId = options.pluginId;
                 const allVersions = options.allVersions;
+                const schemasOnly = options.schemasOnly;
                 const pluginInstances = getPluginInstances(plugins);
                 let targetConfig;
                 if (pluginId) {
@@ -630,17 +698,17 @@ custom_edit_url: null
                     }
                     else {
                         Object.keys(targetConfig).forEach(async function (key) {
-                            await cleanApiDocs(targetConfig[key]);
+                            await cleanApiDocs(targetConfig[key], schemasOnly);
                             if (allVersions) {
-                                await cleanAllVersions(targetConfig[key]);
+                                await cleanAllVersions(targetConfig[key], schemasOnly);
                             }
                         });
                     }
                 }
                 else {
-                    await cleanApiDocs(targetConfig[id]);
+                    await cleanApiDocs(targetConfig[id], schemasOnly);
                     if (allVersions) {
-                        await cleanAllVersions(targetConfig[id]);
+                        await cleanAllVersions(targetConfig[id], schemasOnly);
                     }
                 }
             });
@@ -650,10 +718,12 @@ custom_edit_url: null
                 .usage("<id:version>")
                 .arguments("<id:version>")
                 .option("-p, --plugin-id <plugin>", "OpenAPI docs plugin ID.")
+                .option("--schemas-only", "Clean only schema docs.")
                 .action(async (id, instance) => {
                 var _a;
                 const options = instance.opts();
                 const pluginId = options.pluginId;
+                const schemasOnly = options.schemasOnly;
                 const pluginInstances = getPluginInstances(plugins);
                 let targetConfig;
                 if (pluginId) {
@@ -682,14 +752,16 @@ custom_edit_url: null
                         chalk_1.default.red("Can't use id 'all' for OpenAPI docs versions configuration key.");
                     }
                     else {
-                        await cleanVersions(parentConfig.outputDir);
+                        if (!schemasOnly) {
+                            await cleanVersions(parentConfig.outputDir);
+                        }
                         Object.keys(versions).forEach(async (key) => {
                             const versionConfig = versions[key];
                             const mergedConfig = {
                                 ...parentConfig,
                                 ...versionConfig,
                             };
-                            await cleanApiDocs(mergedConfig);
+                            await cleanApiDocs(mergedConfig, schemasOnly);
                         });
                     }
                 }
@@ -699,7 +771,7 @@ custom_edit_url: null
                         ...parentConfig,
                         ...versionConfig,
                     };
-                    await cleanApiDocs(mergedConfig);
+                    await cleanApiDocs(mergedConfig, schemasOnly);
                 }
             });
         },

package/lib/markdown/createHeading.js

@@ -11,7 +11,7 @@ const utils_1 = require("./utils");
 function createHeading(heading) {
     return [
         (0, utils_1.create)("Heading", {
-            children: (0, utils_1.clean)(heading),
+            children: heading,
             as: "h1",
             className: "openapi__heading",
         }, { inline: true }),

package/lib/markdown/createRequestHeader.js

@@ -11,11 +11,13 @@ const utils_1 = require("./utils");
 function createRequestHeader(header) {
     return [
         (0, utils_1.create)("Heading", {
-            children: header,
             id: header.replace(" ", "-").toLowerCase(),
             as: "h2",
             className: "openapi-tabs__heading",
-        }, { inline: true }),
-        `\n\n`,
+            children: [
+                `<Translate id="theme.openapi.request.title">${header}</Translate>`,
+            ],
+        }),
+        "\n\n",
     ];
 }

package/lib/markdown/createSchema.js

@@ -316,7 +316,7 @@ function createDetailsNode(name, schemaName, schema, required, nullable) {
                                         : required === true, () => [
                                         (0, utils_1.create)("span", {
                                             className: "openapi-schema__required",
-                                            children: "required",
+                                            children: "<Translate id='theme.openapi.schemaItem.required'>required</Translate>",
                                         }),
                                     ]),
                                     (0, utils_1.guard)(schema.deprecated, () => [
@@ -454,7 +454,7 @@ function createPropertyDiscriminator(name, schemaName, schema, discriminator, re
                         (0, utils_1.guard)(required, () => [
                             (0, utils_1.create)("span", {
                                 className: "openapi-schema__required",
-                                children: "required",
+                                children: "<Translate id='theme.openapi.schemaItem.required'>required</Translate>",
                             }),
                         ]),
                     ],