ドキュメントサイトOSS比較：Docusaurus vs Mintlify vs GitBook でAPIドキュメントを自動生成する

Q: Docusaurusで既存のOpenAPIから自動でAPIリファレンスページを生成するにはどうしますか？

A. redocusaurus プラグインを使います。 npm install redocusaurus 後、 docusaurus.config.ts のpluginsに追加してopenapi.yamlのパスを指定するだけで、Redoc UIのAPIリファレンスページが自動生成されます。Swagger UIスタイルが好みなら docusaurus plugin openapi docs （by PaloAlto Networks）も人気で、各エンドポイントが個別のMarkdownページに変換されるためSEOに有利です。どちらも openapi.yaml を更新するだけでAPIドキュメントが自

Q: Docusaurus・Mintlify・GitBookのどれを選ぶべきですか？

A. Docusaurus : フルカスタマイズが必要なOSS・大規模プロダクト向け（React/MDXの知識が必要）。多言語対応・バージョン管理・セルフホストを重視する場合。 Mintlify : スタートアップ・SaaS APIドキュメント向け。設定が少なく数時間で美しいドキュメントが公開できる。OpenAPI統合・AI検索が目当てならMintlify。 GitBook : 技術者でないチームメンバーもMarkdownで編集したい場合や、内部ナレッジベースとAPIドキュメントを一元化したい場合。Web UIで編集できるため非エンジニアにも使いやすい。

Q: Docusaurusをバージョン管理対応にするにはどうしますか？

A. npm run docusaurus docs:version 1.0 を実行すると versioned_docs/version 1.0/ に現在のドキュメントがスナップショットとして保存されます。以降、 docs/ フォルダへの変更はv2.0（current）として扱われます。ユーザーはナビゲーションのバージョンドロップダウンで切り替えできます。デメリット: バージョンが増えるとリポジトリのファイル数が増える。対策: onlyIncludeVersions でビルドするバージョンを限定するか、古いバージョンは archived フォルダに移動して個別のサブドメインでホストする方法があ

ReadmeやNotionに散らばったドキュメントを整理して、開発者向けのプロフェッショナルなドキュメントサイトを構築しましょう。Docusaurus・Mintlify・GitBookはOpenAPI仕様からAPIリファレンスを自動生成でき、バージョン管理・全文検索・多言語対応をすぐに使えます。

ドキュメントサイト構築ツールが必要な場面

APIリファレンス: OpenAPI/Swagger YAMLから美しいAPIリファレンスサイトを自動生成したい
開発者ガイド: チュートリアル・ガイド・リリースノートを一元管理したい
OSS ドキュメント: GitHubのREADMEだけでなく本格的なドキュメントサイトを作りたい
バージョン管理: v1.0・v2.0のドキュメントを並行して管理したい
検索機能: Algolia DocSearchやページ内全文検索を組み込みたい

主要ツールの概要

Docusaurus

Metaが開発するオープンソースのドキュメントサイトジェネレーターです。GitHubスター56k+で最も人気なドキュメントツールの一つ。React/MDXベースでカスタマイズ性が高く、Algolia DocSearch・バージョン管理・多言語対応を標準で提供します。

# Docusaurusのプロジェクト作成
npx create-docusaurus@latest my-docs classic --typescript
cd my-docs

# 開発サーバー起動
npm start

# ビルド
npm run build

# Vercel/Netlifyへデプロイ
npx vercel --prod

// docusaurus.config.ts の設定例
import type { Config } from "@docusaurus/types";
import type * as Preset from "@docusaurus/preset-classic";

const config: Config = {
  title: "My API Docs",
  tagline: "開発者向けAPIドキュメント",
  url: "https://docs.yoursite.com",
  baseUrl: "/",
  onBrokenLinks: "throw",
  onBrokenMarkdownLinks: "warn",
  favicon: "img/favicon.ico",

  // GitHub Pagesの場合
  organizationName: "your-org",
  projectName: "your-docs",

  i18n: {
    defaultLocale: "ja",
    locales: ["ja", "en"],
  },

  presets: [
    [
      "classic",
      {
        docs: {
          sidebarPath: "./sidebars.ts",
          editUrl: "https://github.com/your-org/your-docs/tree/main/",
          // バージョン管理
          includeCurrentVersion: true,
          lastVersion: "current",
          versions: {
            current: {
              label: "v2.0 (最新)",
              path: "",
            },
          },
        },
        blog: {
          showReadingTime: true,
          blogTitle: "リリースノート",
          blogDescription: "APIのアップデートとリリースノート",
          postsPerPage: "ALL",
        },
        theme: {
          customCss: "./src/css/custom.css",
        },
      } satisfies Preset.Options,
    ],
  ],

  plugins: [
    // OpenAPI統合（redocusaurus）
    [
      "redocusaurus",
      {
        specs: [
          {
            spec: "openapi/api-v2.yaml",
            route: "/api-reference/",
          },
        ],
        theme: {
          primaryColor: "#1890ff",
        },
      },
    ],
  ],

  themeConfig: {
    // Algolia DocSearch
    algolia: {
      appId: "YOUR_APP_ID",
      apiKey: "YOUR_SEARCH_API_KEY",
      indexName: "your-index",
    },
    navbar: {
      title: "My API Docs",
      items: [
        {
          type: "docSidebar",
          sidebarId: "tutorialSidebar",
          position: "left",
          label: "ガイド",
        },
        { to: "/api-reference", label: "APIリファレンス", position: "left" },
        { to: "/blog", label: "リリースノート", position: "left" },
        {
          type: "docsVersionDropdown",
          position: "right",
        },
        {
          type: "localeDropdown",
          position: "right",
        },
      ],
    },
  } satisfies Preset.ThemeConfig,
};

export default config;

<!-- docs/api/articles.mdx - MDXでインタラクティブなAPIドキュメント -->
---
sidebar_position: 1
title: 記事API
description: 記事の作成・取得・更新・削除のAPIリファレンス
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

# 記事API

記事の管理に使うエンドポイントです。

## 記事一覧の取得

<Tabs>
  <TabItem value="curl" label="cURL">
    ```bash
    curl -X GET https://api.yoursite.com/articles       -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </TabItem>
  <TabItem value="python" label="Python">
    ```python
    import httpx
    resp = httpx.get(
        "https://api.yoursite.com/articles",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
    )
    print(resp.json())
    ```
  </TabItem>
  <TabItem value="typescript" label="TypeScript">
    ```typescript
    const resp = await fetch("https://api.yoursite.com/articles", {
      headers: { Authorization: `Bearer ${process.env.API_KEY}` },
    });
    const articles = await resp.json();
    ```
  </TabItem>
</Tabs>

Mintlify

AIを活用したドキュメント生成と洗練されたUIで注目されているドキュメントプラットフォームです。MDX形式でコンテンツを管理し、GitHubと連動して自動デプロイします。OpenAPI統合・コードサンプルの自動生成・AI検索（Mintlify Suggest）が特徴です。

# Mintlifyのインストールと初期化
npm install -g mintlify

# ローカルプレビュー
mintlify dev
# → http://localhost:3000

# バリデーション（broken linksのチェック）
mintlify check

// mint.json - Mintlifyの設定ファイル
{
  "name": "My API Docs",
  "logo": {
    "light": "/logo/light.svg",
    "dark": "/logo/dark.svg"
  },
  "favicon": "/favicon.svg",
  "colors": {
    "primary": "#0D9373",
    "light": "#07C983",
    "dark": "#0D9373"
  },
  "topbarLinks": [
    {
      "name": "サポート",
      "url": "mailto:support@yoursite.com"
    }
  ],
  "topbarCtaButton": {
    "name": "ダッシュボード",
    "url": "https://app.yoursite.com"
  },
  "tabs": [
    {
      "name": "APIリファレンス",
      "url": "api-reference"
    }
  ],
  "navigation": [
    {
      "group": "はじめに",
      "pages": ["introduction", "quickstart", "development"]
    },
    {
      "group": "APIリファレンス",
      "pages": [
        "api-reference/introduction",
        {
          "group": "記事",
          "pages": [
            "api-reference/articles/list",
            "api-reference/articles/get",
            "api-reference/articles/create"
          ]
        }
      ]
    }
  ],
  "openapi": ["/api-reference/openapi.yaml"],
  "footerSocials": {
    "github": "https://github.com/your-org/your-project"
  }
}

# openapi.yaml - OpenAPI 3.0仕様（Mintlifyが自動でUIに変換）
openapi: 3.0.0
info:
  title: My API
  description: オープンソースラボのAPI仕様
  version: 2.0.0
servers:
  - url: https://api.yoursite.com
    description: 本番環境

security:
  - bearerAuth: []

paths:
  /articles:
    get:
      summary: 記事一覧の取得
      description: 公開済みの記事を新着順で返します
      operationId: listArticles
      tags: [Articles]
      parameters:
        - name: category
          in: query
          schema:
            type: string
          description: カテゴリスラッグでフィルタ
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        "200":
          description: 記事一覧
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Article"

components:
  schemas:
    Article:
      type: object
      required: [slug, title, status]
      properties:
        slug:
          type: string
          example: "open-source-feature-flags"
        title:
          type: string
          example: "フィーチャーフラグOSS比較"
        status:
          type: string
          enum: [published, draft]
        published_at:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

GitBook

チームのナレッジベースとAPIドキュメントを一元管理できるプラットフォームです。オープンソース版（GitBook CLI）は廃止されましたが、クラウド版の無料プランでOSSプロジェクトのドキュメントを作れます。GitとGitHubの連携でMarkdownファイルをGitBookに同期できます。

# GitBook CLIは廃止済み（2021年）
# 代わりにGitBook.comのWeb UIでセットアップ:
# 1. https://app.gitbook.com で無料アカウント作成
# 2. Space作成 → GitHubリポジトリと連携
# 3. docs/ フォルダのMarkdownを自動同期

# GitBookのSummary.mdで目次構造を定義
# docs/SUMMARY.md

# Summary

## はじめに

- [はじめに](README.md)
- [クイックスタート](getting-started/quickstart.md)
- [インストール](getting-started/installation.md)

## コアコンセプト

- [フィーチャーフラグとは](concepts/feature-flags.md)
- [A/Bテストの設計](concepts/ab-testing.md)

## APIリファレンス

- [認証](api/authentication.md)
- [記事API](api/articles.md)
- [ツールAPI](api/tools.md)

## ガイド

- [Next.jsとの統合](guides/nextjs.md)
- [CI/CDへの組み込み](guides/cicd.md)

機能比較表

比較項目	Docusaurus	Mintlify	GitBook
ライセンス	MIT	商用（無料プランあり）	商用（無料プランあり）
ホスティング	セルフホスト or Vercel	Mintlify Cloud	GitBook Cloud
OpenAPI自動生成	✅ プラグイン	✅ ネイティブ	✅ プラグイン
MDX対応	✅ ネイティブ	✅	❌
バージョン管理	✅	✅	✅
多言語対応	✅ i18n	❌	❌
Algolia検索	✅	✅	✅
AI検索	❌	✅ Mintlify Suggest	❌
カスタマイズ性	★★★★★	★★★☆☆	★★★☆☆
セットアップの速さ	遅い（設定多め）	速い（設定少）	速い（Web UI）
GitHub Actions連携	✅	✅	✅
コードサンプルタブ	✅ MDXで自作	✅ 組み込み	✅
GitHub Stars	56k+	-	-

ドキュメント管理・ナレッジベースツールの選び方はknowledgeカテゴリ（/categories/knowledge）にまとめています。APIテストツールとの連携についてはAPIテスト比較（/categories/devops）も参考にしてください。

FAQ

Q. Docusaurusで既存のOpenAPIから自動でAPIリファレンスページを生成するにはどうしますか？

A. redocusaurusプラグインを使います。npm install redocusaurus後、docusaurus.config.tsのpluginsに追加してopenapi.yamlのパスを指定するだけで、Redoc UIのAPIリファレンスページが自動生成されます。Swagger UIスタイルが好みならdocusaurus-plugin-openapi-docs（by PaloAlto Networks）も人気で、各エンドポイントが個別のMarkdownページに変換されるためSEOに有利です。どちらもopenapi.yamlを更新するだけでAPIドキュメントが自動更新されます。

Q. Docusaurus・Mintlify・GitBookのどれを選ぶべきですか？

A. Docusaurus: フルカスタマイズが必要なOSS・大規模プロダクト向け（React/MDXの知識が必要）。多言語対応・バージョン管理・セルフホストを重視する場合。Mintlify: スタートアップ・SaaS APIドキュメント向け。設定が少なく数時間で美しいドキュメントが公開できる。OpenAPI統合・AI検索が目当てならMintlify。GitBook: 技術者でないチームメンバーもMarkdownで編集したい場合や、内部ナレッジベースとAPIドキュメントを一元化したい場合。Web UIで編集できるため非エンジニアにも使いやすい。

Q. Docusaurusをバージョン管理対応にするにはどうしますか？

A. npm run docusaurus docs:version 1.0 を実行するとversioned_docs/version-1.0/に現在のドキュメントがスナップショットとして保存されます。以降、docs/フォルダへの変更はv2.0（current）として扱われます。ユーザーはナビゲーションのバージョンドロップダウンで切り替えできます。デメリット: バージョンが増えるとリポジトリのファイル数が増える。対策: onlyIncludeVersionsでビルドするバージョンを限定するか、古いバージョンはarchivedフォルダに移動して個別のサブドメインでホストする方法があります。

Q. GitBook無料プランにはどんな制限がありますか？

A. GitBook無料プランの制限: ①メンバー数が5人まで（追加は有料）、②プライベートスペースは1つまで（パブリックスペースは無制限）、③カスタムドメイン対応（docs.yoursite.comなどのサブドメイン設定可能）。OSSプロジェクトのパブリックドキュメントには無料プランで十分なことが多いです。チームでのプライベートナレッジベース用途（社内wiki）には5人制限がすぐ来るためGitBook Pro（$6.7/ユーザー/月）か、セルフホスト可能なOutlineやBookStackへの移行を検討します。

まとめ

ユースケース	推奨ツール
OSS・大規模プロダクト + セルフホスト	Docusaurus
SaaS API + 素早く公開	Mintlify
チームナレッジ + 非エンジニアも編集	GitBook
多言語対応 + 最大カスタマイズ	Docusaurus

ドキュメントサイトOSS比較：Docusaurus vs Mintlify vs GitBook でAPIドキュメントを自動生成する

ドキュメントサイトOSS比較：Docusaurus vs Mintlify vs GitBook でAPIドキュメントを自動生成する

ドキュメントサイト構築ツールが必要な場面

主要ツールの概要

Docusaurus

Mintlify

GitBook

機能比較表

FAQ

Q. Docusaurusで既存のOpenAPIから自動でAPIリファレンスページを生成するにはどうしますか？

Q. Docusaurus・Mintlify・GitBookのどれを選ぶべきですか？

Q. Docusaurusをバージョン管理対応にするにはどうしますか？

Q. GitBook無料プランにはどんな制限がありますか？

まとめ

関連外部リソース

他の記事も読む

全文検索OSS比較：Meilisearch vs Typesense vs OpenSearch でAlgolia代替をセルフホスト

ロードバランサーOSS比較：Nginx vs HAProxy vs Traefik でAWS ELB代替をセルフホスト

GitOpsツールOSS比較：ArgoCD vs Flux vs Rancher Fleet でKubernetes継続デリバリー

OSS導入、自社だけで悩まない。