Plugins

OpenAPI Plugin

Generate API documentation from OpenAPI/Swagger specs

The OpenAPI plugin reads your OpenAPI (Swagger) spec files and auto-generates full API documentation pages — complete with parameter tables, response examples, cURL snippets, and an interactive playground for testing endpoints live.

Installation

pnpm add @barodoc/plugin-openapi@latest

Quick Start

1. Place your OpenAPI spec file in the project root:

my-docs/
├── openapi.yaml          ← your spec
├── barodoc.config.json
└── src/content/docs/...

2. Add the plugin to barodoc.config.json:

{
  "plugins": [
    ["@barodoc/plugin-openapi", {
      "specFile": "openapi.yaml",
      "basePath": "api",
      "groupBy": "tags",
      "baseUrl": "https://api.example.com",
      "playground": true
    }]
  ]
}

3. Add the generated pages to your navigation:

{
  "navigation": [
    {
      "group": "API Reference",
      "pages": ["api/users", "api/auth", "api/billing"]
    }
  ]
}

Page slugs are derived from your spec’s tag names — lowercased and hyphenated. For example, a tag named User Management becomes api/user-management.

4. (Optional) Add a tab for quick access:

{
  "tabs": [
    { "label": "Docs", "href": "/docs/introduction" },
    { "label": "API", "href": "/docs/api/users" }
  ]
}

How It Works

At build time, the plugin:

1. Reads your OpenAPI 3.0+ spec file (YAML or JSON)
2. Groups endpoints by tags (or paths)
3. Generates .mdx files into src/content/docs/{basePath}/
4. Each file includes imports for API components and playground

The generated pages are regular docs pages — they appear in the sidebar, support search, and share the same theme.

Multiple API Specs

If your project has multiple APIs (e.g. public API, admin API, webhooks), pass an array to specFile:

{
  "plugins": [
    ["@barodoc/plugin-openapi", {
      "specFile": [
        {
          "file": "api/public.yaml",
          "basePath": "api/public",
          "baseUrl": "https://api.example.com/v1"
        },
        {
          "file": "api/admin.yaml",
          "basePath": "api/admin",
          "baseUrl": "https://admin.example.com"
        },
        {
          "file": "api/webhooks.yaml",
          "basePath": "api/webhooks",
          "groupBy": "paths"
        }
      ],
      "playground": true
    }]
  ]
}

Each entry generates its own set of pages under its own basePath. Add them to navigation separately:

{
  "navigation": [
    {
      "group": "Public API",
      "pages": ["api/public/users", "api/public/products"]
    },
    {
      "group": "Admin API",
      "pages": ["api/admin/dashboard", "api/admin/settings"]
    },
    {
      "group": "Webhooks",
      "pages": ["api/webhooks/events"]
    }
  ]
}

Project structure with multiple specs

my-docs/
├── api/
│   ├── public.yaml        ← Public API spec
│   ├── admin.yaml         ← Admin API spec
│   └── webhooks.yaml      ← Webhooks spec
├── barodoc.config.json
└── src/content/docs/
    ├── en/
    │   └── ...            ← your docs
    └── api/               ← auto-generated (don't edit)
        ├── public/
        │   ├── users.mdx
        │   └── products.mdx
        ├── admin/
        │   ├── dashboard.mdx
        │   └── settings.mdx
        └── webhooks/
            └── events.mdx

Generated Output

Each generated page includes:

API Playground

When playground: true (default), each endpoint gets an interactive playground:

• Authentication — Bearer Token, API Key (header/query), Basic Auth
• Parameter inputs — Text fields, enum dropdowns, required field validation
• Request body editor — JSON editor with auto-generated example body
• Code snippets — cURL, JavaScript (fetch), Python (requests), Node.js
• Response viewer — Syntax-highlighted JSON body, headers, status, timing, size
• Request history — Last 5 requests stored in IndexedDB for quick re-testing

Set playground: false to generate documentation-only pages without the interactive form.

Options Reference

Single spec (string)

Multiple specs (array)

When specFile is an array, each entry supports:

Supported Spec Features

The plugin reads the following from your OpenAPI spec:

• info — title, version, description (used in API overview)
• paths — all operations with their HTTP methods
• parameters — query, path, header, cookie params with types and descriptions
• requestBody — content types and JSON schema
• responses — status codes, descriptions, and response schemas
• components/schemas — $ref resolution for nested schemas
• tags — used for grouping endpoints into pages
• Enum values, format hints (date, email, int64), and nested objects