docusaurus-plugin-openapi-docs 4.5.1 → 4.6.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,28 @@ 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.             |
 
 ### sidebarOptions
 
@@ -222,6 +226,49 @@ 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` |
 
+## 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 +330,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 +372,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

@@ -78,7 +78,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 +104,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 +160,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 +234,15 @@ 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;
+                if (isSchemasOnly && item.type !== "schema") {
+                    return;
+                }
                 if (item.type === "api") {
                     // opportunity to compress JSON
                     // const serialize = (o: any) => {
@@ -250,9 +258,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;
@@ -335,25 +348,36 @@ 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,
+            });
+            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}"`));
+                }
+            }));
+        }
         try {
             fs_1.default.rmSync(`${apiDir}/schemas`, { recursive: true });
             console.log(chalk_1.default.green(`Cleanup succeeded for "${apiDir}/schemas"`));
@@ -363,14 +387,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 +458,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 +486,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 +514,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 +533,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 +546,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 +575,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 +598,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 +611,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 +626,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 +658,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 +678,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 +712,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 +731,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>",
                             }),
                         ]),
                     ],

package/lib/markdown/index.js

@@ -37,7 +37,8 @@ function createApiPageMD({ title, api: { deprecated, "x-deprecated-description":
         `import StatusCodes from "@theme/StatusCodes";\n`,
         `import OperationTabs from "@theme/OperationTabs";\n`,
         `import TabItem from "@theme/TabItem";\n`,
-        `import Heading from "@theme/Heading";\n\n`,
+        `import Heading from "@theme/Heading";\n`,
+        `import Translate from "@docusaurus/Translate";\n\n`,
         (0, createHeading_1.createHeading)(title),
         (0, createMethodEndpoint_1.createMethodEndpoint)(method, path),
         infoPath && (0, createAuthorization_1.createAuthorization)(infoPath),
@@ -82,7 +83,7 @@ function createSchemaPageMD({ schema }) {
     return (0, utils_1.render)([
         `import Schema from "@theme/Schema";\n`,
         `import Heading from "@theme/Heading";\n\n`,
-        (0, createHeading_1.createHeading)(title.replace(utils_1.lessThan, "<").replace(utils_1.greaterThan, ">")),
+        (0, createHeading_1.createHeading)(title),
         (0, createDescription_1.createDescription)(description),
         (0, utils_1.create)("Schema", {
             schema: schema,

package/lib/openapi/createSchemaExample.js

@@ -58,7 +58,14 @@ function sampleFromProp(name, prop, obj, context) {
         return obj;
     }
     // TODO: handle discriminators
-    if (prop.oneOf) {
+    // Check for explicit example/examples first (OAS 3.1 support)
+    if (prop.example !== undefined) {
+        obj[name] = prop.example;
+    }
+    else if (prop.examples !== undefined && prop.examples.length > 0) {
+        obj[name] = prop.examples[0];
+    }
+    else if (prop.oneOf) {
         obj[name] = (0, exports.sampleFromSchema)(prop.oneOf[0], context);
     }
     else if (prop.anyOf) {
@@ -77,10 +84,14 @@ const sampleFromSchema = (schema = {}, context) => {
     try {
         // deep copy schema before processing
         let schemaCopy = JSON.parse(JSON.stringify(schema));
-        let { type, example, allOf, properties, items, oneOf, anyOf } = schemaCopy;
+        let { type, example, examples, allOf, properties, items, oneOf, anyOf, const: constant, } = schemaCopy;
         if (example !== undefined) {
             return example;
         }
+        // OAS 3.1 / JSON Schema: examples is an array
+        if (examples !== undefined && examples.length > 0) {
+            return examples[0];
+        }
         if (oneOf) {
             if (properties) {
                 const combinedSchemas = (0, merge_1.default)(schemaCopy, oneOf[0]);
@@ -169,6 +180,9 @@ const sampleFromSchema = (schema = {}, context) => {
         if (shouldExcludeProperty(schemaCopy, context)) {
             return undefined;
         }
+        if (constant) {
+            return constant;
+        }
         return primitive(schemaCopy);
     }
     catch (err) {

package/lib/openapi/createSchemaExample.test.d.ts

@@ -0,0 +1 @@
+export {};