Overview​
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, interactive API reference docs.
Key Features:
- Compatible: Works with Swagger 2.0 and OpenAPI 3.0.
- 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.
Compatibility Matrix​
Docusaurus OpenAPI Docs | Docusaurus |
---|---|
2.0.x (current) | 2.4.1 - 2.4.3 |
1.7.3 (legacy) | 2.0.1 - 2.2.0 |
If you"re building a Docusaurus site from scratch the easiest way to get started is by installing from template.
Bootstrapping from Template (new Docusaurus site)​
Run the following to bootstrap a Docsaurus v2 site (classic theme) with docusaurus-openapi-docs
:
npx create-docusaurus@2.4.3 my-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" (unless you know better).
cd my-website
yarn start
Installation (existing Docusaurus site)​
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.
Plugin:
yarn add docusaurus-plugin-openapi-docs
Theme:
yarn add docusaurus-theme-openapi-docs
Configuration​
Configuring the plugin​
The plugin configuration is comprised of options that are read by the CLI while generating and cleaning API docs.
See plugin configuration options for a more thorough reference.
The following is an example configuration to help get you started.
plugins: [
[
"docusaurus-plugin-openapi-docs",
{
id: "openapi",
docsPluginId: "<your docs plugin id>", // e.g. "classic" or the plugin-content-docs id
config: {
petstore: { // "petstore" is considered the <id> that you will reference in the CLI
specPath: "examples/petstore.yaml", // path or URL to the OpenAPI spec
outputDir: "api/petstore", // output directory for generated *.mdx and sidebar.js files
sidebarOptions: {
groupPathsBy: "tag", // generate a sidebar.js slice that groups operations by tag
},
}
}
},
]
],
Configuring the theme​
To use the theme you"ll need to define it under themes
in docusaurus.config.js
:
themes: ["docusaurus-theme-openapi-docs"] // exports ApiItem and ApiDemoPanel
Finally, you"ll need to replace @theme/DocItem
with @theme/ApiItem
as your docItemComponent
. Where you do this will depend on whether you are using @docusaurus/preset-classic
or a standalone @docusaurus/plugin-content-docs
to render your docs (see examples below).
The @theme/ApiItem
component is designed to be a drop-in replacement for @theme/DocItem
that supports rendering OpenAPI documentation while maintaining backwards compatibility with non-API docs. In other words, it can be used for rendering both API and non-API docs.
presets: [
[
"classic",
({
docs: {
sidebarPath: require.resolve("./sidebars.js"),
editUrl:
"https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
docLayoutComponent: "@theme/DocPage",
docItemComponent: "@theme/ApiItem" // add @theme/ApiItem here
},
blog: {
showReadingTime: true,
editUrl:
"https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/"
},
theme: {
customCss: require.resolve("./src/css/custom.css")
}
})
]
]
plugins: [
[
"@docusaurus/plugin-content-docs",
{
path: "docs",
breadcrumbs: true,
routeBasePath: "docs",
include: ["**/*.md", "**/*.mdx"],
sidebarPath: "sidebars.js",
docLayoutComponent: "@theme/DocPage",
docItemComponent: "@theme/ApiItem", // add @theme/ApiItem here
},
],
],
Complete example​
For a complete example of how to configure docusaurus-plugin-openapi-docs
and docusaurus-theme-openapi-docs
see the demo configuration.
CLI Usage​
After you've installed and configured the plugin and theme, the CLI can be used to generate
and clean
API docs.
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 <id> Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).
gen-api-docs:version <id:version> Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).
clean-api-docs <id> Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).
clean-api-docs:version <id:version> Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (if
enabled).
If you're configuring multiple docusaurus-plugin-openapi-docs
instances use the -p
or --plugin-id
option to specify which plugin instance to run the commands against.
Options:
-p, --plugin-id <plugin> OpenAPI docs plugin ID.
-h, --help display help for command
Generating OpenAPI Docs​
The following command will generate API docs for all of the OpenAPI specifications referenced in your
docusaurus-plugin-openapi-docs
config.
yarn docusaurus gen-api-docs all
The following command will generate API docs for a specific
id
:
yarn docusaurus gen-api-docs <id>
Example:
yarn docusaurus gen-api-docs petstore
Cleaning API Docs​
Occasionally you may need to clean and re-generate API docs, especially following changes to your OpenAPI specification(s).
The following command will clean all API docs referenced in your
docusaurus-plugin-openapi-docs
config.
yarn docusaurus clean-api-docs all
The following command will clean API docs for a specific
id
:
yarn docusaurus clean-api-docs <id>
Example:
yarn docusaurus clean-api-docs petstore
Versioning OpenAPI docs​
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
Examples:
yarn docusaurus gen-api-docs:version petstore:all
yarn docusaurus gen-api-docs:version petstore:1.0.0
Substitue all
with a specific version ID to generate/clean a specific version. Generating for all
or a specific version ID will automatically update the versions.json
file.
See versions options for a list of available options. For a complete example of how to configure versining see the demo configuration.
Plugin Configuration Options​
The docusaurus-plugin-openapi-docs
plugin can be configured with the following options:
Name | Type | Default | Description |
---|---|---|---|
id | string | null | A unique plugin id. |
docsPluginId | string | null | The ID associated with the plugin-content-docs or preset instance used to render the OpenAPI docs (e.g. "your-plugin-id", "classic", "default"). |
config​
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 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. |
sidebarOptions​
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 . |
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. |
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
.
versions​
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​
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 |
If a config option is not provided, its default markdown generator will be used.
This config option is intended for advanced users who wish to highly customize the markdown content and layout of generated pages.
Developer Quick Start​
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
Credits​
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
Contributors​
Support​
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.