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

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)

Plugin:

yarn add docusaurus-plugin-openapi-docs

Theme:

yarn add docusaurus-theme-openapi-docs

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

Here is an example of properly configuring 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"),
          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,
          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: "api", // plugin id
        docsPluginId: "classic", // id of plugin-content-docs or preset for rendering docs
        config: {
          petstore: { // the  referenced when running CLI commands
            specPath: "examples/petstore.yaml", // path to OpenAPI spec, URLs supported
            outputDir: "api/petstore", // output directory for generated files
            sidebarOptions: { // optional, instructs plugin to generate sidebar.js
              groupPathsBy: "tag", // group sidebar items by operation "tag"
            },
          },
          burgers: {
            specPath: "examples/food/burgers/openapi.yaml",
            outputDir: "api/food/burgers",
          }
        }
      },
    ]
  ],
  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 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:

CLI Usage

Usage: docusaurus  [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                                    Tag a new docs version
  gen-api-docs                                         Generates OpenAPI docs in MDX file format and sidebar.js (if enabled).
  gen-api-docs:version                         Generates versioned OpenAPI docs in MDX file format, versions.js and sidebar.js (if enabled).
  clean-api-docs                                       Clears the generated OpenAPI docs MDX files and sidebar.js (if enabled).
  clean-api-docs:version                       Clears the versioned, generated OpenAPI docs MDX files, versions.json and sidebar.js (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 

Example:

yarn docusaurus gen-api-docs burgers

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

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 

Example:

yarn docusaurus clean-api-docs burgers

> The example above will remove all API docs relative to burgers.

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

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//docusaurus-openapi-docs.git
cd docusaurus-openapi-docs
yarn
yarn build-packages
yarn watch:demo

Support

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