josh-cena/docusaurus-plugin-openapi

🦕 OpenAPI plugin for generating API reference docs in Docusaurus v2.

Docusaurus OpenAPI (beta)

OpenAPI plugin for generating API reference docs in Docusaurus v2.

💥 Breaking Changes: v0.1.0 -> v0.2.0

Preset usage

Install the preset in your docusaurus project by running:

// with npm
npm install docusaurus-preset-openapi

// with yarn
yarn add docusaurus-preset-openapi

The OpenAPI preset can be used as a drop-in replacement to @docusaurus/preset-classic:

/* docusaurus.config.js */

{
  presets: [
    [
      "docusaurus-preset-openapi",
      {
        // ... options
      },
    ],
  ],
}

The default preset options will expose a route, /api, and look for an OpenAPI definition at ./openapi.json.

To explictly configure this, add an api stanza as follows:

/* docusaurus.config.js */

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

To add a link to the API page, add a new item to the navbar by updating themeConfig.navbar.items:

/* docusaurus.config.js */

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

Multiple OpenAPI Definitions

To have more than one OpenAPI pages, add additional OpenAPI plugin instances:

/* docusaurus.config.js */

{
  presets: [
    [
      'docusaurus-preset-openapi',
      {
        api: {
          // id: 'cars', // omitted => default instance
          path: 'cars/openapi.json',
          routeBasePath: 'cars',
          // ... other options
        },
      },
    ],
  ],
  plugins: [
    [
      'docusaurus-plugin-openapi',
      {
        id: 'trains',
        path: 'trains/openapi.json',
        routeBasePath: 'trains',
        // ... other options
      },
    ],
    [
      'docusaurus-plugin-openapi',
      {
        id: 'bikes',
        path: 'bikes/openapi.json',
        routeBasePath: 'bikes',
        // ... other options
      },
    ],
  ],
}

This will create routes for /cars, /trains and /bikes.

Note: One instance of the plugin is included in the preset. All additional plugin instances will require an id.