@signalwire-community/docusaurus-preset-openapi

Docusaurus OpenAPI

OpenAPI plugin for generating API reference docs in Docusaurus v2.

Installation

Install the preset in your docusaurus project by running:

// with npm
npm install docusaurus-preset-openapi

// with yarn
yarn add docusaurus-preset-openapi

Usage

1. Add your OpenAPI definition to the root of your site dir as openapi.json (See Configuration options below).

2. The OpenAPI preset can be used as a drop-in replacement for @docusaurus/preset-classic, replace it as follows:

   /* docusaurus.config.js */
   
   {
     presets: [
       [
         "docusaurus-preset-openapi",
         {
           // docs: { ... },
           // blogs: { ... },
           // theme: { ... },
         },
       ],
     ],
   }
   

3. Add a link to the API section of your site by updating themeConfig.navbar.items:

   /* docusaurus.config.js */
   
   {
     themeConfig: {
       navbar: {
         items: [
           // ... other items
           { to: "/api", label: "API", position: "left" },
           // ... other items
         ],
       },
     },
   }
   

Configuration

The OpenAPI plugin can be configured with the following options:

Name	Type	Default	Description
path	string	'openapi.json'	Path to OpenAPI definition (json or yaml) on filesystem relative to site dir.
routeBasePath	string	'api'	URL route for the API section of your site. DO NOT include a trailing slash. Use / for shipping API without base path.
sidebarCollapsible	boolean	true	Whether sidebar categories are collapsible by default.
sidebarCollapsed	boolean	true	Whether sidebar categories are collapsed by default.
apiLayoutComponent	string	'@theme/ApiPage'	Root Layout component of each API page.
apiItemComponent	string	'@theme/ApiItem'	Main API container, with demo panel, pagination, etc.
remarkPlugins	any[]	[]	Remark plugins passed to MDX.
rehypePlugins	any[]	[]	Rehype plugins passed to MDX.
beforeDefaultRemarkPlugins	any[]	[]	Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins.
beforeDefaultRehypePlugins	any[]	[]	Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins.

Example:

/* docusaurus.config.js */

{
  presets: [
    [
      "docusaurus-preset-openapi",
      {
        api: {
          path: "api/cars.yaml",
          routeBasePath: "cars",
          // ... other options
        }
      },
    ],
  ],
}

Changelog

0.6.0 (Jun 23, 2022)

High-level enhancements

• Compatibility with Docusaurus 2.0.0-beta.21

Other enhancements and bug fixes

• Compatibility with Docusaurus 2.0.0-beta.21 (#185)
• Resolve allOf references (#184)
• Fetch openapi from a URL (#173)
• Fix Cypress test (#157)
• Add display name extension for tags (#154)