docusaurus-openapi-docs/demo/docs/intro.mdx at 4644633613894bebf5868f9dbf3b251b7736176b · PaloAltoNetworks/docusaurus-openapi-docs

sidebar_position

hide_title

sidebar_label

title

slug

image

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 when combined with 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.
Flexible: Supports single, multi and even micro OpenAPI specs.
Extensible: Recognizes common vendor extensions for customizing your docs. See Vendor Extensions for details.

Supported Vendor Extensions

The plugin extracts a number of vendor extensions from the OpenAPI spec to enrich the generated docs. The theme renders some of these values as part of the UI.

Extension	Purpose
`x-codeSamples`	Operation level code snippets displayed in the API Explorer.
`x-tagGroups`	Groups tags in the sidebar navigation.
`x-tags`	Assigns tags to schema objects so they appear with tagged operations.
`x-position`	Controls ordering of items in the sidebar.
`x-logo` / `x-dark-logo`	Provides logos for light and dark themes on the intro page.
`x-deprecated-description`	Custom text shown for deprecated operations.
`x-webhooks`	Defines webhook events.
`x-displayName`	Overrides tag display names.
`x-enumDescription` / `x-enumDescriptions`	Documents enum values.

Other ReDoc specific extensions such as x-circular-ref, x-code-samples (deprecated), x-examples, x-ignoredHeaderParameters, x-nullable, x-servers, x-traitTag, x-additionalPropertiesName, and x-explicitMappingOnly are ignored when extracting custom data.

Compatibility Matrix

Docusaurus OpenAPI Docs	Docusaurus
4.0.x (current)	`3.5.0 - 3.8.1`
3.0.x (end-of-support)	`3.0.1 - 3.4.0`
2.2.3 (legacy)	`2.4.1 - 2.4.3`
1.7.3 (end-of-support)	`2.0.1 - 2.2.0`

:::tip If you're building a Docusaurus site from scratch, the easiest way to get started is by installing from template. :::

Bootstrapping from Template (new Docusaurus site)

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

npx create-docusaurus@3.8.1 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

If all goes well, you should be greeted by a brand new Docusaurus site that includes API reference docs for the ubiquitous Petstore API!

Installation (existing Docusaurus site)

:::note Both the plugin and theme are currently designed to pair with a specific Docusaurus release. The Docusaurus badge in the README.md and at the top of this page will always reflect the current compatible versions. :::

Plugin

yarn add docusaurus-plugin-openapi-docs

Theme

yarn add docusaurus-theme-openapi-docs

Configuration

Configuring `docusaurus.config.ts` (Plugin and theme usage)

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

:::note Instructions may differ slightly for sites that haven't migrated to typescript. :::

// docusaurus.config.ts
// note that parts of the complete config were left out for brevity
import type * as Preset from "@docusaurus/preset-classic";
import type { Config } from "@docusaurus/types";
import type * as Plugin from "@docusaurus/types/src/plugin";
import type * as OpenApiPlugin from "docusaurus-plugin-openapi-docs";

{
  presets: [
    [
      "classic",
      {
        docs: {
          sidebarPath: "./sidebars.ts",
          docItemComponent: "@theme/ApiItem", // Derived from docusaurus-theme-openapi
        },
        theme: {
          customCss: "./src/css/custom.css",
        },
      } satisfies Preset.Options,
    ],
  ],

  plugins: [
    [
      'docusaurus-plugin-openapi-docs',
      {
        id: "api", // plugin id
        docsPluginId: "classic", // configured for preset-classic
        config: {
          petstore: {
            specPath: "examples/petstore.yaml",
            outputDir: "docs/petstore",
            sidebarOptions: {
              groupPathsBy: "tag",
            },
          } satisfies OpenApiPlugin.Options,
        }
      },
    ]
  ],
  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:

Name	Type	Default	Description
`id`	`string`	`null`	A unique plugin ID.
`docsPlugin`	`string`	`@docusaurus/plugin-content-docs`	The plugin used to render the OpenAPI docs (ignored if the plugin instance referenced by `docsPluginId` is a `preset`).
`docsPluginId`	`string`	`null`	The plugin ID associated with the `preset` or configured `docsPlugin` instance used to render the OpenAPI docs (e.g. "your-plugin-id", "classic", "default").

config

config can be configured with the following options:

Name	Type	Default	Description
`specPath`	`string`	`null`	Designated URL or path to the source of an OpenAPI specification file or directory of multiple OpenAPI specification files.
`outputDir`	`string`	`null`	Desired output path for generated MDX and sidebar files.
`proxy`	`string`	`null`	Optional: Proxy URL to prepend to base URL when performing API requests from browser.
`template`	`string`	`null`	Optional: Customize MDX content with a desired template (path to file holding template).
`templateGenerators`	`object`	`null`	Optional: Customize MDX content with generator functions. See below for a list of supported options.
`infoTemplate`	`string`	`null`	Optional: Customize MDX content for info pages only.
`tagTemplate`	`string`	`null`	Optional: Customize MDX content for tag pages only.
`schemaTemplate`	`string`	`null`	Optional: Customize MDX content for schema pages only.
`downloadUrl`	`string`	`null`	Optional: Designated URL for downloading OpenAPI specification. (requires `info` section/doc)
`hideSendButton`	`boolean`	`null`	Optional: If set to `true`, hides the “Send API Request” button in the API demo panel.
`showExtensions`	`boolean`	`null`	Optional: If set to `true`, renders operation‑level vendor‑extensions in descriptions.
`sidebarOptions`	`object`	`null`	Optional: Set of options for sidebar configuration. See below for a list of supported options.
`version`	`string`	`null`	Optional: Version assigned to a single or micro‑spec API specified in `specPath`.
`label`	`string`	`null`	Optional: Version label used when generating the version‑selector dropdown menu.
`baseUrl`	`string`	`null`	Optional: Base URL for versioned docs in the version‑selector dropdown.
`versions`	`object`	`null`	Optional: Options for versioning configuration. See below for a list of supported options.
`markdownGenerators`	`object`	`null`	Optional: Customize MDX content via generator functions. See below for a list of supported options.
`showSchemas`	`boolean`	`null`	Optional: If set to `true`, generates standalone schema pages and adds them to the sidebar.

sidebarOptions

sidebarOptions can be configured with the following options:

Name	Type	Default	Description
`groupPathsBy`	`string`	`null`	Organize and group sidebar slice by specified option. Note: Currently, `groupPathsBy` only contains support for grouping by `tag` and `tagGroup`.
`categoryLinkSource`	`string`	`null`	Defines what source to use for rendering category link pages when grouping paths by tag. The supported options are as follows: `tag`: Sets the category link config type to `generated-index` and uses the tag description as the link config description. `info`: Sets the category link config type to `doc` and renders the `info` section as the category link (recommended only for multi/micro-spec scenarios). `none`: Does not create pages for categories, only groups that can be expanded/collapsed.
`sidebarCollapsible`	`boolean`	`true`	Whether sidebar categories are collapsible by default.
`sidebarCollapsed`	`boolean`	`true`	Whether sidebar categories are collapsed by default.
`customProps`	`object`	`null`	Additional props for customizing a sidebar item.
`sidebarGenerators`	`object`	`null`	Optional: Customize sidebar rendering with callback functions.

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:

Name	Type	Default	Description
`specPath`	`string`	`null`	Designated URL or path to the source of an OpenAPI specification file or a directory of micro OpenAPI specification files.
`outputDir`	`string`	`null`	Desired output path for versioned, generated MDX files.
`label`	`string`	`null`	Optional: Version label used when generating the version selector dropdown menu.
`baseUrl`	`string`	`null`	Optional: Version base URL used when generating the version selector dropdown menu.
`downloadUrl`	`string`	`null`	Optional: Designated URL for downloading the versioned OpenAPI specification.

All versions will automatically inherit sidebarOptions from the parent/base config.

templateGenerators

templateGenerators can be configured with the following options:

Name	Type	Default	Description
`createIntroTemplateMD`	`function`	`null`	Optional: Returns a string of the raw markdown body for introduction page. Function type: `() => string`
`createInfoTemplateMD`	`function`	`null`	Optional: Returns a string of the raw markdown body for info pages. Function type: `() => string`
`createTagTemplateMD`	`function`	`null`	Optional: Returns a string of the raw markdown body for tag pages. Function type: `() => string`
`createSchemaTemplateMD`	`function`	`null`	Optional: Returns a string of the raw markdown body for schema pages. Function type: `() => string`

Example:

petstore31: {
  specPath: "examples/petstore-3.1.yaml",
  proxy: "https://cors.pan.dev",
  outputDir: "docs/petstore31",
  sidebarOptions: {
    groupPathsBy: "tag",
    categoryLinkSource: "tag",
  },
  downloadUrl: "/petstore-3.1.yaml",
  hideSendButton: false,
  showSchemas: true,
  templateGenerators: {
    createIntroTemplateMD: myCustomIntroMdGenerator
  }, // customize markdown template generator
} satisfies OpenApiPlugin.Options,

markdownGenerators

markdownGenerators can be configured with the following options:

Name	Type	Default	Description
`createApiPageMD`	`function`	`null`	Optional: Returns a string of the raw markdown body for API pages. Function type: `(pageData: ApiPageMetadata) => string`
`createInfoPageMD`	`function`	`null`	Optional: Returns a string of the raw markdown body for info pages. Function type: `(pageData: InfoPageMetadata) => string`
`createTagPageMD`	`function`	`null`	Optional: Returns a string of the raw markdown body for tag pages. Function type: `(pageData: TagPageMetadata) => string`
`createSchemaPageMD`	`function`	`null`	Optional: Returns a string of the raw markdown body for schema pages. Function type: `(pageData: SchemaPageMetadata) => string`

Example:

petstore31: {
  specPath: "examples/petstore-3.1.yaml",
  proxy: "https://cors.pan.dev",
  outputDir: "docs/petstore31",
  sidebarOptions: {
    groupPathsBy: "tag",
    categoryLinkSource: "tag",
  },
  downloadUrl: "/petstore-3.1.yaml",
  hideSendButton: false,
  showSchemas: true,
  markdownGenerators: { createApiPageMD: myCustomApiMdGenerator }, // customize MDX with markdown generator
} satisfies OpenApiPlugin.Options,

sidebarGenerators

sidebarGenerators can be configured with the following options:

Name	Type	Default	Description
`createDocItem`	`function`	`null`	Optional: Returns a `SidebarItemDoc` object containing metadata for a sidebar item. Function type: `(item: ApiPageMetadata \| SchemaPageMetadata, context: { sidebarOptions: SidebarOptions; basePath: string }) => SidebarItemDoc`

CLI Usage

After you've installed and configured the plugin and theme, the CLI can be used to generate and clean API docs.

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

Generating OpenAPI Docs

To generate all OpenAPI docs, run the following command from the root directory of your project:

:::note This will generate API docs for all of the OpenAPI specification (OAS) files referenced in your docusaurus-plugin-openapi-docs config. :::

yarn docusaurus gen-api-docs all

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 petstore

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

Example:

yarn docusaurus clean-api-docs petstore

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 <id>:all

Examples:

yarn docusaurus gen-api-docs:version petstore:all

yarn docusaurus gen-api-docs:version petstore:1.0.0

:::tip Substitute all with a specific version ID to generate or clean a specific version. Generating for all or a single version ID will automatically update the versions.json file. :::

See versions options for a list of available options. For a complete example of how to configure versioning see the demo configuration.

Developer Quick Start

Looking to make a contribution? Make sure to check 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

Credits

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

Contributors

Support

See SUPPORT.md for our support agreement and guidelines.

If you believe you found a bug or have an idea you'd like to suggest you may report an issue or start a discussion.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Overview

Supported Vendor Extensions

Compatibility Matrix

Bootstrapping from Template (new Docusaurus site)

Installation (existing Docusaurus site)

Plugin

Theme

Configuration

Configuring `docusaurus.config.ts` (Plugin and theme usage)

Plugin Configuration Options

config

sidebarOptions

templateGenerators

markdownGenerators

sidebarGenerators

CLI Usage

Generating OpenAPI Docs

Cleaning API Docs

Versioning OpenAPI docs

Developer Quick Start

Credits

Contributors

Support

FilesExpand file tree

intro.mdx

Latest commit

History

intro.mdx

File metadata and controls

Overview

Supported Vendor Extensions

Compatibility Matrix

Bootstrapping from Template (new Docusaurus site)

Installation (existing Docusaurus site)

Plugin

Theme

Configuration

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

Plugin Configuration Options

config

sidebarOptions

templateGenerators

markdownGenerators

sidebarGenerators

CLI Usage

Generating OpenAPI Docs

Cleaning API Docs

Versioning OpenAPI docs

Developer Quick Start

Credits

Contributors

Support

Configuring `docusaurus.config.ts` (Plugin and theme usage)