@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.1 (Aug 3, 2022)

Other enhancements and bug fixes

• Persist server variables configuration (#202)
• fix(theme): new location for theme icons (#203)
• Fix: loading failed for local openapi json file on Windows (#197)
• ensure description from schema is not ignored (#194)
• Fix illegal color value bug (#196)
• chore: update template version (#195)
• Escape html in parameter names (#189)
• Category squashing (#188)