docusaurus-openapi-docs

The docusaurus-plugin-openapi-docs package extends the Docusaurus CLI to generate MDX documentation from OpenAPI specifications (Swagger 2.0 and OpenAPI 3.x). When used in conjunction with the docusaurus-theme-openapi-docs theme, it produces high-quality, styled API reference documentation.

Key features include:

• Fast conversion: Large specs are converted to MDX in seconds.
• Infima styling: Uses the same styling framework as Docusaurus.
• Flexibility: Supports single, multi, and micro OpenAPI specifications.
• Extensibility: Supports common vendor extensions for customization.

The docusaurus-plugin-openapi-docs package extends the Docusaurus CLI with commands to generate MDX files from OpenAPI specifications (Swagger 2.0 and OpenAPI 3.x). When used with the docusaurus-theme-openapi-docs theme, it renders high-quality API reference documentation.

Key features include:

• Fast conversion: Converts large specs to MDX in seconds.
• Flexible: Supports single, multi, and micro OpenAPI specs.
• Extensible: Supports common vendor extensions to customize documentation UI.
• Compatible: Integrates with Docusaurus plugin-content-docs.

You can control which page is displayed when a sidebar category is clicked using several methods:

• Generated Index: Use the generated-index feature to create an index of all paths/endpoints available under a specific tag.
• Tag Descriptions: Use the description field of an OpenAPI tag to define the content displayed when the category is clicked.
• Spec Info: Use the info section of an OpenAPI specification as the landing page for a category (primarily intended for micro-specs).

Documentation content is managed via specific file paths depending on whether you are editing the current unreleased docs or a previously released version:

• Unreleased/Next docs: Edit files directly in the docs/ folder (e.g., docs/hello.md updates http://localhost:3000/docs/next/hello).
• Versioned docs: Edit files within the versioned_docs/ directory (e.g., versioned_docs/version-1.0/hello.md updates http://localhost:3000/docs/hello).

The plugin supports grouping paths by tagGroup. It uses the first path group as the "group by" value and the path itself as one of the tags under that category.

To implement this:

1. Use the x-tagGroups extension in your OpenAPI specification (added to the root OpenAPI object).
2. If showSchemas: true is configured in the plugin, an additional Schemas category will be created and placed at the end of the sidebar, following all tagGroups categories.

The versions.json file contains metadata used for building UI navigation and breadcrumb components.

• Generation: It is automatically generated and updated every time gen-api-docs:version is executed (for a specific version or for all versions).
• Deletion: It is only automatically deleted when you run yarn docusaurus clean-api-docs:version <your-api-config-key>:all.

Because Docusaurus uses MDX, you can import and use React components directly inside your Markdown files. You can also define components within the Markdown file using the export keyword.

This allows for highly interactive documentation where components can handle state, clicks, or custom styling.

export const Highlight = ({ children, color }) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: "20px",
      color: "#fff",
      padding: "10px",
      cursor: "pointer",
    }}
    onClick={() => {
      alert(`You clicked the color ${color} with label ${children}`);
    }}
  >
    {children}
  </span>
);

This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !

The OpenAPI plugin can group schema objects into the same sidebar categories as path objects using the x-tag extension.

Behavior:

• When groupPathsBy is set to tag, any schema object containing x-tag will be gathered into the relevant tag's category alongside the paths.
• Note: If showSchemas is not configured, schema objects with x-tags will still be included in the relevant tag's category sidebar.