Skip to content

Commit bfcc26d

Browse files
sserratasserrata
authored
docs: expand list of ignored vendor extensions (PaloAltoNetworks#1184)
1 parent dab3823 commit bfcc26d

File tree

4 files changed

+65
-0
lines changed

4 files changed

+65
-0
lines changed

‎demo/docs/intro.mdx‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,25 @@ Key Features:
5151
- **Fast:** Convert large OpenAPI specs into MDX docs in seconds. 🔥
5252
- **Stylish:** Based on the same [Infima styling framework](https://infima.dev/) that powers the Docusaurus UI.
5353
- **Flexible:** Supports single, multi and _even micro_ OpenAPI specs.
54+
- **Extensible:** Recognizes common vendor extensions for customizing your docs. See [Vendor Extensions](./vendor-extensions) for details.
55+
56+
## Supported Vendor Extensions
57+
58+
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.
59+
60+
| Extension | Purpose |
61+
| ------------------------------------------ | ----------------------------------------- |
62+
| `x-codeSamples` | Operation level code snippets displayed in the API Explorer. |
63+
| `x-tagGroups` | Groups tags in the sidebar navigation. |
64+
| `x-tags` | Assigns tags to schema objects so they appear with tagged operations. |
65+
| `x-position` | Controls ordering of items in the sidebar. |
66+
| `x-logo` / `x-dark-logo` | Provides logos for light and dark themes on the intro page. |
67+
| `x-deprecated-description` | Custom text shown for deprecated operations. |
68+
| `x-webhooks` | Defines webhook events. |
69+
| `x-displayName` | Overrides tag display names. |
70+
| `x-enumDescription` / `x-enumDescriptions` | Documents enum values. |
71+
72+
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.
5473

5574
---
5675

‎demo/docs/vendor-extensions.mdx‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
id: vendor-extensions
3+
hide_title: true
4+
sidebar_label: Vendor Extensions
5+
title: Vendor Extensions
6+
---
7+
8+
## Overview
9+
10+
The OpenAPI plugin and theme recognize several [vendor extensions](https://swagger.io/specification/#specification-extensions) for customizing the generated documentation. Supported extensions include:
11+
12+
| Extension | Purpose |
13+
|-----------|---------|
14+
| `x-codeSamples` | Provide language specific code snippets for operations. These are displayed in the API Explorer panel. |
15+
| `x-tagGroups` | Group tags in the sidebar navigation. |
16+
| `x-tags` | Assign tags to schema objects so they appear with tagged operations when `groupPathsBy: tag` is enabled. |
17+
| `x-position` | Explicit ordering of operations in the generated sidebar. |
18+
| `x-logo` / `x-dark-logo` | Display light and dark logos on the introduction page. |
19+
| `x-deprecated-description` | Custom text shown alongside deprecated operations. |
20+
| `x-webhooks` | Define webhook events under the `x-webhooks` key. |
21+
| `x-displayName` | Override tag names used for grouping. |
22+
| `x-enumDescription` / `x-enumDescriptions` | Document individual enum values. |
23+
24+
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.

‎demo/sidebars.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,10 @@ const sidebars: SidebarsConfig = {
4646
type: "doc",
4747
id: "advanced",
4848
},
49+
{
50+
type: "doc",
51+
id: "vendor-extensions",
52+
},
4953
{
5054
type: "category",
5155
label: "Customization",

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,24 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
222222
| --------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
223223
| `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` |
224224

225+
## Supported Vendor Extensions
226+
227+
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.
228+
229+
| Extension | Purpose |
230+
| ------------------------------------------ | --------------------------------------------------------------------- |
231+
| `x-codeSamples` | Operation level code snippets displayed in the API Explorer. |
232+
| `x-tagGroups` | Groups tags in the sidebar navigation. |
233+
| `x-tags` | Assigns tags to schema objects so they appear with tagged operations. |
234+
| `x-position` | Controls ordering of items in the sidebar. |
235+
| `x-logo` / `x-dark-logo` | Provides logos for light and dark themes on the intro page. |
236+
| `x-deprecated-description` | Custom text shown for deprecated operations. |
237+
| `x-webhooks` | Defines webhook events. |
238+
| `x-displayName` | Overrides tag display names. |
239+
| `x-enumDescription` / `x-enumDescriptions` | Documents enum values. |
240+
241+
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.
242+
225243
## CLI Usage
226244

227245
```bash

0 commit comments

Comments
 (0)