OpenAPI plugin for generating API reference docs in Docusaurus v2.

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 by setting docItemComponent to @theme/ApiItem, a custom component included in 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.
• Capable: Supports single, multi and even micro OpenAPI specs.

Plugin:

yarn add docusaurus-plugin-openapi-docs

Theme:

yarn add docusaurus-theme-openapi-docs

Here is an example of properly configuring your docusaurus.config.js file for docusaurus-plugin-openapi-docs and docusaurus-theme-openapi-docs usage.

// docusaurus.config.js

{
  presets: [
  [
    "classic",
    /** @type {import('@docusaurus/preset-classic').Options} */
    ({
      docs: {
        sidebarPath: require.resolve("./sidebars.js"),
        // Please change this to your repo.
        // Remove this to remove the "edit this page" links.
        editUrl:
          "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
        docLayoutComponent: "@theme/DocPage",
        docItemComponent: "@theme/ApiItem" // Derived from docusaurus-theme-openapi-docs
      },
      blog: {
        showReadingTime: true,
        // Please change this to your repo.
        // Remove this to remove the "edit this page" links.
        editUrl:
          "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/"
      },
      theme: {
        customCss: require.resolve("./src/css/custom.css")
      }
    })
  ]
],

  plugins: [
      'docusaurus-plugin-openapi-docs',
      {
        id: "apiDocs",
        docsPluginId: "classic",
        config: {
          petstore: { // Note: petstore key is treated as the <id> and can be used to specify an API doc instance when using CLI commands
            specPath: "examples/petstore.yaml", // Path to designated spec file
            outputDir: "api/petstore", // Output directory for generated .mdx docs
            sidebarOptions: {
              groupPathsBy: "tag",
            },
          },
          burgers: {
            specPath: "examples/food/burgers/openapi.yaml",
            outputDir: "api/food/burgers",
          }
        }
      },
    ]
  ],
  themes: ["docusaurus-theme-openapi-docs"] // Allows use of @theme/ApiItem and other 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.

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

config can be configured with the following options:

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.

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

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 burgers

The example above will only generate API docs relative to burgers.

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 burgers

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

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.

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

npx [email protected] 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

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

Please read SUPPORT.md for details on how to get support for this project.