Docusaurus OpenAPI Doc Generator

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 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.

Compatibility Matrix

Bootstrapping from Template (new Docusaurus site)

Run the following to bootstrap a Docusaurus v3 site (classic theme) with docusaurus-openapi-docs:

npx create-docusaurus@3.9.2 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".

If all goes well, you should be greeted by a brand new Docusaurus site that includes API reference docs for the ubiquitous Petstore API!

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

Configuring docusaurus.config.ts (Plugin and theme usage)

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 with docusaurus-theme-openapi-docs by setting docItemComponent to @theme/ApiItem.

Plugin Configuration Options

The docusaurus-plugin-openapi-docs plugin can be configured with the following options:

config

config can be configured with the following options:

sidebarOptions

sidebarOptions can be configured with the following options:

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 can be configured with the following options:

All versions will automatically inherit sidebarOptions from the parent/base config.

markdownGenerators

markdownGenerators can be configured with the following options:

sidebarGenerators

sidebarGenerators can be configured with the following options:

Performance Optimization

By default, externalJsonProps is enabled to optimize Docusaurus build times. This externalizes large JSON objects to separate files, significantly improving build performance for large OpenAPI specs.

How it works:

• With externalJsonProps: true (default): Large JSON props are written to separate .json files and loaded via require(). This bypasses MDX AST processing entirely, allowing the bundler to handle JSON more efficiently.

• With externalJsonProps: false: Large JSON objects (responses, request bodies, parameters) are embedded directly in the MDX. The MDX compiler must parse these into an AST and serialize them back, which can be slow for deeply nested schemas.

When to disable:

You may set externalJsonProps: false if you have custom tooling that depends on parsing the MDX files directly:

petstore: {
  specPath: "examples/petstore.yaml",
  outputDir: "docs/petstore",
  externalJsonProps: false, // Disable if needed for custom tooling
} satisfies OpenApiPlugin.Options,

Theme Configuration Options

The docusaurus-theme-openapi-docs theme can be configured with the following options in themeConfig.api:

Example:

// docusaurus.config.ts
{
  themeConfig: {
    api: {
      proxy: "https://cors.pan.dev",  // Site-wide proxy (can be overridden per-spec in plugin config)
      authPersistance: "localStorage",
      requestTimeout: 60000, // 60 seconds
      requestCredentials: "omit", // Prevent cookies from being sent with requests
    },
  },
}

CLI Usage

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)

Generating OpenAPI Docs

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.

If you have multiple versions of the same API, gen-api-docs only generates the latest. To generate all versions, use the --all-versions flag.

Example:

yarn docusaurus gen-api-docs all --all-versions

This will generate API docs for all versions of all the OpenAPI specification (OAS) files referenced in your docusaurus-plugin-openapi-docs config.

To generate only schema MDX files—without updating the sidebar or requiring showSchemas in your plugin config—use the --schemas-only flag:

yarn docusaurus gen-api-docs petstore --schemas-only

This command writes the schema pages to the configured output directory while leaving other generated docs untouched.

The --schemas-only flag is also available for gen-api-docs:version.

Cleaning API Docs

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.

If you have multiple versions of the same API, clean-api-docs only cleans the latest. To clean all versions, use the --all-versions flag.

Example:

yarn docusaurus clean-api-docs all --all-versions

This will clean API docs for all versions of all the OpenAPI specification (OAS) files referenced in your docusaurus-plugin-openapi-docs config.

To clean only schema docs while leaving API, info, and tag docs untouched, use the --schemas-only flag:

yarn docusaurus clean-api-docs petstore --schemas-only

The --schemas-only flag is also available for clean-api-docs:version.

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

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 a versions.json file.

Substitute all with a specific version ID to generate or clean a specific version. Generating for all or a single version ID will automatically update the versions.json file.

Developer Quick Start

Looking to make a contribution? Make sure to check 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.