From 4a21400cf15de7b1a983758b733d95c71f240631 Mon Sep 17 00:00:00 2001
From: Steven Serrata <9343811+sserrata@users.noreply.github.com>
Date: Mon, 30 Jun 2025 15:39:44 -0500
Subject: [PATCH] docs: expand list of ignored vendor extensions

---
 demo/docs/intro.mdx                           | 19 +++++++++++++++
 demo/docs/vendor-extensions.mdx               | 24 +++++++++++++++++++
 demo/sidebars.ts                              |  4 ++++
 .../docusaurus-plugin-openapi-docs/README.md  | 18 ++++++++++++++
 4 files changed, 65 insertions(+)
 create mode 100644 demo/docs/vendor-extensions.mdx

diff --git a/demo/docs/intro.mdx b/demo/docs/intro.mdx
index 2d0b052fd..d4779c3f7 100644
--- a/demo/docs/intro.mdx
+++ b/demo/docs/intro.mdx
@@ -51,6 +51,25 @@ Key Features:
 - **Fast:** Convert large OpenAPI specs into MDX docs in seconds. 🔥
 - **Stylish:** Based on the same [Infima styling framework](https://infima.dev/) that powers the Docusaurus UI.
 - **Flexible:** Supports single, multi and _even micro_ OpenAPI specs.
+- **Extensible:** Recognizes common vendor extensions for customizing your docs. See [Vendor Extensions](./vendor-extensions) for details.
+
+## 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.
 
 ---
 
diff --git a/demo/docs/vendor-extensions.mdx b/demo/docs/vendor-extensions.mdx
new file mode 100644
index 000000000..f0aede3e8
--- /dev/null
+++ b/demo/docs/vendor-extensions.mdx
@@ -0,0 +1,24 @@
+---
+id: vendor-extensions
+hide_title: true
+sidebar_label: Vendor Extensions
+title: Vendor Extensions
+---
+
+## Overview
+
+The OpenAPI plugin and theme recognize several [vendor extensions](https://swagger.io/specification/#specification-extensions) for customizing the generated documentation. Supported extensions include:
+
+| Extension | Purpose |
+|-----------|---------|
+| `x-codeSamples` | Provide language specific code snippets for operations. These are displayed in the API Explorer panel. |
+| `x-tagGroups` | Group tags in the sidebar navigation. |
+| `x-tags` | Assign tags to schema objects so they appear with tagged operations when `groupPathsBy: tag` is enabled. |
+| `x-position` | Explicit ordering of operations in the generated sidebar. |
+| `x-logo` / `x-dark-logo` | Display light and dark logos on the introduction page. |
+| `x-deprecated-description` | Custom text shown alongside deprecated operations. |
+| `x-webhooks` | Define webhook events under the `x-webhooks` key. |
+| `x-displayName` | Override tag names used for grouping. |
+| `x-enumDescription` / `x-enumDescriptions` | Document individual enum values. |
+
+Other ReDoc 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 detected but ignored when extracting custom extensions.
diff --git a/demo/sidebars.ts b/demo/sidebars.ts
index ce7873efd..b57fd2ca5 100644
--- a/demo/sidebars.ts
+++ b/demo/sidebars.ts
@@ -46,6 +46,10 @@ const sidebars: SidebarsConfig = {
       type: "doc",
       id: "advanced",
     },
+    {
+      type: "doc",
+      id: "vendor-extensions",
+    },
     {
       type: "category",
       label: "Customization",
diff --git a/packages/docusaurus-plugin-openapi-docs/README.md b/packages/docusaurus-plugin-openapi-docs/README.md
index fe5bb12c3..73121243d 100644
--- a/packages/docusaurus-plugin-openapi-docs/README.md
+++ b/packages/docusaurus-plugin-openapi-docs/README.md
@@ -222,6 +222,24 @@ 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` |
 
+## 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