@albertigroup/docusaurus-plugin-swagger

A Docusaurus plugin that renders Swagger UI inline in your documentation site.

Features

• Renders Swagger UI via a dedicated route in your Docusaurus site
• Built on swagger-ui-react v5
• TypeScript-first, fully typed plugin and component API
• Compatible with Docusaurus v3

Requirements

| Peer dependency | Version | |--------------------|-----------| | @docusaurus/core | ^3.10.1 | | react | ^18.0.0 | | react-dom | ^18.0.0 |

Installation

# pnpm
pnpm add @albertigroup/docusaurus-plugin-swagger

# npm
npm install @albertigroup/docusaurus-plugin-swagger

# yarn
yarn add @albertigroup/docusaurus-plugin-swagger

Usage

1. Register the plugin

In your docusaurus.config.ts:

import type { Config } from '@docusaurus/types';

const config: Config = {
  // ...
  plugins: [
    [
      '@albertigroup/docusaurus-plugin-swagger',
      {
        id: 'my-api',
        defaultSpecPath: './swagger/my-api.yaml',
        routePath: '/api',
        specFileName: 'my-api.yaml', // used for i18n
      },
    ],
  ],
};

export default config;

2. Multiple instances

You can register the plugin multiple times with different id values to expose multiple APIs:

plugins: [
  [
    '@albertigroup/docusaurus-plugin-swagger',
    {
      id: 'public-api',
      defaultSpecPath: './swagger/public-api.yaml',
      routePath: '/api/public',
      specFileName: 'public-api.yaml',
    },
  ],
  [
    '@albertigroup/docusaurus-plugin-swagger',
    {
      id: 'admin-api',
      defaultSpecPath: './swagger/admin-api.yaml',
      routePath: '/api/admin',
      specFileName: 'admin-api.yaml',
    },
  ],
],

3. i18n

Place your translated YAML files at:

i18n/{locale}/docusaurus-plugin-swagger/{specFileName}

Examples:

i18n/en/docusaurus-plugin-swagger/public-api.yaml
i18n/es/docusaurus-plugin-swagger/admin-api.yaml

Plugin options

| Option | Type | Required | Default | Description | |-------------------|----------|----------|-------------|---------------------------------------------------------| | id | string | No | 'default' | Unique plugin instance ID (required for multi-instance) | | defaultSpecPath | string | Yes | — | Path to the default locale OpenAPI/Swagger YAML file | | routePath | string | Yes | — | Base path where Swagger UI will be rendered | | specFileName | string | No | — | File name used to resolve locale-specific spec files |

License

MIT © Alberti Group