The docusaurus-plugin-openapi-docs
package extends the Docusaurus CLI with commands for generating MDX using the OpenAPI specification as the source. The resulting MDX is fully compatible with plugin-content-docs and can be used to render beautiful reference API docs when combined with the docusaurus-theme-openapi-docs
theme.
Key Features:
- Compatible: Works with Swagger 2.0 and OpenAPI 3.x.
- Fast: Convert large OpenAPI specs into MDX docs in seconds. 🔥
- Stylish: Based on the same Infima styling framework that powers the Docusaurus UI.
- Flexible: Supports single, multi and even micro OpenAPI specs.
Docusaurus OpenAPI Docs | Docusaurus |
---|---|
4.0.x (current) | 3.5.0 - 3.5.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 |
Run the following to bootstrap a Docsaurus v3 site (classic theme) with docusaurus-openapi-docs
:
npx create-docusaurus@3.5.2my-website --package-manager yarn
When prompted to select a template choose
Git repository
.
Template Repository URL:
https://github.com/PaloAltoNetworks/docusaurus-template-openapi-docs.git
When asked how the template repo should be cloned choose "copy".
cd my-website
yarn start
If all goes well, you should be greeted by a brand new Docusaurus site that includes API reference docs for the ubiquitous Petstore API!
Both the plugin and theme are currently designed to pair with a specific Docusaurus release. The Docusaurus badge in the
README.md
and at the top of this page will always reflect the current compatible versions.
yarn add docusaurus-plugin-openapi-docs
yarn add docusaurus-theme-openapi-docs
Here is an example of properly configuring docusaurus.config.ts
for docusaurus-plugin-openapi-docs
and docusaurus-theme-openapi-docs
usage.
Note: Instructions may differ slightly for sites that haven't migrated to typescript.
// docusaurus.config.ts
// note that parts of the complete config were left out for brevity
import type * as Preset from "@docusaurus/preset-classic";
import type { Config } from "@docusaurus/types";
import type * as Plugin from "@docusaurus/types/src/plugin";
import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs";
{
presets: [
[
"classic",
{
docs: {
sidebarPath: "./sidebars.ts",
docItemComponent: "@theme/ApiItem", // Derived from docusaurus-theme-openapi
},
theme: {
customCss: "./src/css/custom.css",
},
} satisfies Preset.Options,
],
],
plugins: [
[
'docusaurus-plugin-openapi-docs',
{
id: "api", // plugin id
docsPluginId: "classic", // configured for preset-classic
config: {
petstore: {
specPath: "examples/petstore.yaml",
outputDir: "docs/petstore",
sidebarOptions: {
groupPathsBy: "tag",
},
} satisfies OpenApiPlugin.Options,
}
},
]
],
themes: ["docusaurus-theme-openapi-docs"], // export theme components
}
Note: You may optionally configure a dedicated
@docusaurus/plugin-content-docs
instance for use withdocusaurus-theme-openapi-docs
by settingdocItemComponent
to@theme/ApiItem
.
The docusaurus-plugin-openapi-docs
plugin can be configured with the following options:
Name | Type | Default | Description |
---|---|---|---|
id |
string |
null |
A unique plugin ID. |
docsPlugin |
string |
@docusaurus/plugin-content-docs |
The plugin used to render the OpenAPI docs (ignored if the plugin instance referenced by docsPluginId is a preset ). |
docsPluginId |
string |
null |
The plugin ID associated with the preset or configured docsPlugin instance used to render the OpenAPI docs (e.g. "your-plugin-id", "classic", "default"). |
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. |
ouputDir |
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. |
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 API demo panel |
showExtensions |
boolean |
null |
Optional: If set to true , renders operation-level vendor-extensions in description. |
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 single or micro-spec API specified in specPath . |
label |
string |
null |
Optional: Version label used when generating version selector dropdown menu. |
baseUrl |
string |
null |
Optional: Version base URL used when generating version selector dropdown menu. |
versions |
object |
null |
Optional: Set of options for versioning configuration. See below for a list of supported options. |
markdownGenerators |
object |
null |
Optional: Customize MDX content with a set of options for specifying markdown generator functions. See below for a list of supported options. |
showSchemas |
boolean |
null |
Optional: If set to true , generates schema pages and adds them to the sidebar. |
sidebarOptions
can be configured with the following options:
Name | Type | Default | Description |
---|---|---|---|
groupPathsBy |
string |
null |
Organize and group sidebar slice by specified option. Note: Currently, groupPathsBy only contains support for grouping by tag and tagGroup . |
categoryLinkSource |
string |
null |
Defines what source to use for rendering category link pages when grouping paths by tag. The supported options are as follows: tag : Sets the category link config type to generated-index and uses the tag description as the link config description. info : Sets the category link config type to doc and renders the info section as the category link (recommended only for multi/micro-spec scenarios). none : Does not create pages for categories, only groups that can be expanded/collapsed. |
sidebarCollapsible |
boolean |
true |
Whether sidebar categories are collapsible by default. |
sidebarCollapsed |
boolean |
true |
Whether sidebar categories are collapsed by default. |
customProps |
object |
null |
Additional props for customizing a sidebar item. |
sidebarGenerators |
object |
null |
Optional: Customize sidebar rendering with callback functions. |
You may optionally configure a
sidebarOptions
. In doing so, an individualsidebar.js
slice with the configured options will be generated within the respectiveoutputDir
.
versions
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 micro OpenAPI specification files. |
ouputDir |
string |
null |
Desired output path for versioned, generated MDX files. |
label |
string |
null |
Optional: Version label used when generating version selector dropdown menu. |
baseUrl |
string |
null |
Optional: Version base URL used when generating version selector dropdown menu. |
All versions will automatically inherit
sidebarOptions
from the parent/base config.
markdownGenerators
can be configured with the following options:
Name | Type | Default | Description |
---|---|---|---|
createApiPageMD |
function |
null |
Optional: Returns a string of the raw markdown body for API pages. Function type: (pageData: ApiPageMetadata) => string
|
createInfoPageMD |
function |
null |
Optional: Returns a string of the raw markdown body for info pages. Function type: (pageData: InfoPageMetadata) => string
|
createTagPageMD |
function |
null |
Optional: Returns a string of the raw markdown body for tag pages. Function type: (pageData: TagPageMetadata) => string
|
createSchemaPageMD |
function |
null |
Optional: Returns a string of the raw markdown body for schema pages. Function type: (pageData: SchemaPageMetadata) => string
|
sidebarGenerators
can be configured with the following options:
Name | Type | Default | Description |
---|---|---|---|
createDocItem |
function |
null |
Optional: Returns a SidebarItemDoc object containing metadata for a sidebar item.Function type: (item: ApiPageMetadata | SchemaPageMetadata, context: { sidebarOptions: SidebarOptions; basePath: string }) => SidebarItemDoc
|
Usage: docusaurus <command> [options]
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
build [options] [siteDir] Build website.
swizzle [options] [themeName] [componentName] [siteDir] Wraps or ejects the original theme files into website folder for customization.
deploy [options] [siteDir] Deploy website to GitHub pages.
start [options] [siteDir] Start the development server.
serve [options] [siteDir] Serve website locally.
clear [siteDir] Remove build artifacts.
write-translations [options] [siteDir] Extract required translations of your site.
write-heading-ids [options] [siteDir] [files...] Generate heading ids in Markdown content.
docs:version <version> Tag a new docs version
gen-api-docs [options] <id> Generates OpenAPI docs in MDX file format and sidebar.ts (if enabled).
gen-api-docs:version [options] <id:version> Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.ts (if
enabled).
clean-api-docs [options] <id> Clears the generated OpenAPI docs MDX files and sidebar.ts (if enabled).
clean-api-docs:version [options] <id:version> Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.ts
(if enabled)
To generate all OpenAPI docs, run the following command from the root directory of your project:
yarn docusaurus gen-api-docs all
This will generate API docs for all of the OpenAPI specification (OAS) files referenced in your
docusaurus-plugin-openapi-docs
config.
You may also generate OpenAPI docs for a single path or OAS by specifying the unique id
:
yarn docusaurus gen-api-docs <id>
Example:
yarn docusaurus gen-api-docs petstore
The example above will only generate API docs relative to
petstore
.
To clean/remove all API Docs, run the following command from the root directory of your project:
yarn docusaurus clean-api-docs all
You may also remove a particular set of API docs by specifying the unique id
of your desired spec instance.
yarn docusaurus clean-api-docs <id>
Example:
yarn docusaurus clean-api-docs petstore
The example above will remove all API docs relative to
burgers
.
To generate all versioned OpenAPI docs, run the following command from the root directory of your project:
yarn docusaurus gen-api-docs:version <id>:all
Example:
yarn docusaurus gen-api-docs:version petstore:all
This will generate API docs for all of the OpenAPI specification (OAS) files referenced in your
versions
config and will also generate aversions.json
file.
Substitue
all
with a specific version ID to generate/clean a specific version. Generating forall
or a specific version ID will automatically update theversions.json
file.
Looking to make a contribution? Make sure to checkout out our contributing guide.
After forking the main repository, run the following:
git clone https://github.com/<your account>/docusaurus-openapi-docs.git
cd docusaurus-openapi-docs
yarn
yarn build-packages
yarn watch:demo
Special thanks to @bourdakos1 (Nick Bourdakos), the author of docusaurus-openapi, which this project is heavily based on.
For more insight into why we decided to completely fork see #47
See SUPPORT.md for our support agreement and guidelines.
If you believe you found a bug or have an idea you'd like to suggest you may report an issue or start a discussion.