Skip to content

docs: harmonize top-level README with plugin README #1446

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sserrata merged 1 commit into from
May 1, 2026
Merged

docs: harmonize top-level README with plugin README #1446

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 22 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ 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 [Supported Vendor Extensions](#supported-vendor-extensions) for details.

## Compatibility Matrix

Expand Down Expand Up @@ -125,6 +126,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",
},
Expand Down Expand Up @@ -165,6 +167,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
| `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. |
Expand All @@ -174,7 +177,6 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
| `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. |
| `maskCredentials` | `boolean` | `true` | _Optional:_ If set to `false`, disables credential masking in generated code snippets. By default, credentials are masked for security. |
| `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
Expand All @@ -191,6 +193,7 @@ The `docusaurus-plugin-openapi-docs` plugin can be configured with the following
| `sidebarGenerators` | `object` | `null` | Optional: Customize sidebar rendering with callback functions. |

> You may optionally configure a `sidebarOptions`. In doing so, an individual `sidebar.js` slice with the configured options will be generated within the respective `outputDir`.
> Use `x-position` vendor extension (or the front matter `position`) on operations to explicitly order sidebar items.

`versions` can be configured with the following options:

Expand Down Expand Up @@ -272,6 +275,24 @@ Example:
}
```

## 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
Expand Down
3 changes: 2 additions & 1 deletion packages/docusaurus-plugin-openapi-docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ 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 [Supported Vendor Extensions](#supported-vendor-extensions) for details.

## Compatibility Matrix

Expand Down Expand Up @@ -437,7 +438,7 @@ yarn watch:demo

## Credits

Special thanks to @bourdakos1 (Nick Bourdakos), the author of [docusaurus-openapi](https://github.com/cloud-annotations/docusaurus-openapi), which this project is heavily based on.
Special thanks to [@bourdakos1](https://github.com/bourdakos1) (Nick Bourdakos), the author of [docusaurus-openapi](https://github.com/cloud-annotations/docusaurus-openapi), which this project is heavily based on.

For more insight into why we decided to completely fork see [#47](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/47)

Expand Down
Loading