ソフトウェアエンジニアリングチームが Mintlify と GitHub を使用して API ドキュメントを構築および自動化する方法

ソフトウェアエンジニアリングチームは、急速に変化するコードベースと API ドキュメントの同期を維持することに苦慮することが多く、その結果、エンドポイントの破損、パラメータの欠落、開発者の混乱を招く原因となっています。Mintlify と GitHub を組み合わせた Docs-as-Code（コードとしてのドキュメント）手法を採用することで、チームはアプリケーションコードと同等の厳密さでドキュメントを管理できるようになります。ドキュメントファイルを Git リポジトリ内で直接ホストし、Mintlify GitHub App を介して自動デプロイを設定し、OpenAPI 仕様を継続的インテグレーション（CI）パイプラインに統合することで、エンジニアリング組織は応答性の高いインタラクティブな開発者ポータルを自動生成できます。この構成により、手動でのドキュメント更新が不要になり、API リファレンスとデプロイ済みコードの一致が保証され、Pull Request プレビューを通じたシームレスなレビューワークフローが確立されます。

Mintlify と GitHub による Docs-as-Code アーキテクチャの理解

Mintlify は Docs-as-Code の原則に基づいて動作し、ドキュメントのソースファイルは GitHub リポジトリ内の本番コードと並行または隣接して配置されます。静的なコンテンツ管理システム（CMS）や独立した Wiki ソフトウェアに依存する代わりに、Markdown、MDX コンポーネント、および構造化設定ファイルを使用してドキュメントを定義します。

アーキテクチャは主に 4 つのコアコンポーネントで構成されます。

設定ファイル（mint.json）： サイトのメタデータ、ブランドアイデンティティ、ナビゲーションツリー、検索設定、および外部または内部の OpenAPI 仕様へのリンクを定義する中心的な設定ファイル。
コンテンツファイル（.mdx）： 標準的なテキストフォーマットとインタラクティブな React スタイルのコンポーネント（パラメータテーブル、タブ、展開可能なアコーディオン、コードグループなど）を組み合わせた拡張 Markdown ファイル。
OpenAPI 仕様（openapi.json / openapi.yaml）： REST API の標準化された機械可読な記述。Mintlify がこれを解析して、インタラクティブなエンドポイントリファレンスと「Try It」リクエストプレイグラウンドを生成します。
Mintlify GitHub 統合： リポジトリの Webhook をリッスンし、変更が本番ブランチにマージされたときにクラウドビルドを自動的にトリガーし、Pull Request 用のプレビュー環境を生成するネイティブ GitHub App。

+-----------------------------------------------------------------------+
|                           GitHub Repository                           |
|                                                                       |
|  +----------------+  +--------------------+  +---------------------+  |
|  |   mint.json    |  |  docs/**/*.mdx     |  |    openapi.json     |  |
|  | (Site Config)  |  | (Guides & Pages)   |  | (API Specification) |  |
|  +----------------+  +--------------------+  +---------------------+  |
+-----------------------------------------------------------------------+
            |                                         ^
            | (Push to main / Open PR)                | (CI Auto-Sync)
            v                                         |
+-----------------------+                 +-----------------------+
|  Mintlify GitHub App  |                 |  GitHub Actions CI/CD |
|  - Validates syntax   |                 |  - Extract spec from  |
|  - Builds static docs |                 |    backend code       |
|  - Posts PR preview   |                 |  - Commit / Trigger   |
+-----------------------+                 +-----------------------+
            |
            v
+-----------------------------------------------------------------------+
|                      Production Documentation Site                    |
|         (Interactive Developer Portal & Live API Playground)          |
+-----------------------------------------------------------------------+

ドキュメントリポジトリのセットアップ

エンジニアリングチームは、専用のドキュメントリポジトリまたは既存のアプリケーションモノレポ内のいずれかで Mintlify を導入できます。明確なディレクトリ構成から始めることで、わかりやすいナビゲーションと明快な CI/CD 境界が確保されます。

1. リポジトリ構成

標準的な Mintlify ドキュメントワークスペースは以下のファイル構成に従います。

my-docs-repo/
├── .github/
│   └── workflows/
│       └── sync-api-spec.yml
├── docs/
│   ├── api-reference/
│   │   ├── authentication.mdx
│   │   └── errors.mdx
│   ├── guides/
│   │   ├── quickstart.mdx
│   │   └── rate-limits.mdx
│   └── openapi.json
└── mint.json

2. `mint.json` の設定

mint.json ファイルは、ビジュアルテーマ、トップレベルのナビゲーション、および API リファレンスの取り込みを制御します。チームは navigation 配列を設定して概念ガイドを整理し、OpenAPI 仕様で定義された API エンドポイントを自動的にリンクします。

{
  "$schema": "https://mintlify.com/schema.json",
  "name": "Acme Developer Platform",
  "logo": {
    "dark": "/logo/dark.svg",
    "light": "/logo/light.svg"
  },
  "favicon": "/favicon.svg",
  "colors": {
    "primary": "#0F52BA",
    "light": "#4B9CD3",
    "dark": "#002D62"
  },
  "navigation": [
    {
      "group": "Getting Started",
      "pages": [
        "docs/guides/quickstart",
        "docs/guides/rate-limits"
      ]
    },
    {
      "group": "API Reference",
      "pages": [
        "docs/api-reference/authentication",
        "docs/api-reference/errors"
      ],
      "openapi": "docs/openapi.json"
    }
  ],
  "api": {
    "baseUrl": "https://api.acme.com/v1"
  }
}

3. Mintlify CLI を使用したローカル開発

エンジニアは GitHub にプッシュする前に、ドキュメントの変更をローカルで検証する必要があります。Mintlify CLI はホットリロード対応のローカル開発サーバーを提供します。

CLI をグローバルにインストールするか、npx を使用して実行します。
```
npm install -g mint
```
mint.json が含まれるディレクトリに移動し、開発サーバーを起動します。
```
mint dev
```
ブラウザで http://localhost:3000 を開きます。.mdx ファイル、mint.json、または OpenAPI スキーマに加えられた変更は即座にリロードされます。

Mintlify GitHub App によるデプロイの自動化

GitHub と Mintlify を結ぶ中核的な自動化メカニズムは Mintlify GitHub App です。一度インストールすれば、手動のビルドおよびデプロイスクリプトが不要になります。

インストールとブランチ設定

Mintlify ダッシュボードにログインし、Settings > Git Settings に移動します。
Install GitHub App をクリックし、組織と対象のリポジトリを選択します。
Deployment Branch（通常は main）を設定します。このブランチにコミットがプッシュまたはマージされるたびに、Mintlify は本番ビルドをトリガーします。
ドキュメントがモノレポのサブフォルダー（/docs など）内にある場合は、サブディレクトリのトグルを有効にしてパスを指定します。これにより、ドキュメントフォルダー内のファイルが変更された場合にのみ Mintlify がトリガーされるようにビルドが制限されます。

Pull Request プレビューとレビューゲート

エンジニアがドキュメントファイルを変更する Pull Request を作成すると、GitHub App は自動的にビルドチェックを実行し、一意のプレビュー URL を添えて PR にコメントします。

ビジュアル QA（品質保証）： レビュー担当者は、マージ前にプレビュー環境でレンダリングされた MDX コンポーネント、フォーマット、およびインタラクティブなプレイグラウンドを直接確認できます。
構文検証： 不正な形式の Markdown 要素、リンク切れの内部リンク、または無効な JSON スキーマが含まれている場合、ビルドチェックは失敗し、PR が main にマージされるのをブロックします。
職能横断的なコラボレーション： テクニカルライター、プロダクトマネージャー、開発者が、コードレビューで使用されるのと同じインターフェース内でドキュメント文面の変更をレビューできます。

GitHub Actions による OpenAPI 仕様更新の自動化

概念ガイドは MDX で手動作成されますが、API リファレンスドキュメントは常にソースコードから直接派生させるべきです。バックエンドエンジニアがエンドポイントのルーティング、リクエストペイロード、またはレスポンススキーマを変更した際には、自動化パイプラインによってドキュメントディレクトリ内の OpenAPI 仕様ファイルを更新する必要があります。

モノレポにおける仕様の同期

API サービスコード（FastAPI、Express、NestJS、Go など）がドキュメントと同一リポジトリ内に存在するモノレポでは、GitHub Actions を使用してコミット時に最新の仕様を生成し、ドキュメントフォルダーを最新の状態に維持できます。

以下の GitHub Actions ワークフローは、バックエンドサービスから OpenAPI スキーマを抽出し、Mintlify のデプロイをトリガーする例を示しています。

name: Sync OpenAPI Spec and Deploy Docs

on:
  push:
    branches:
      - main
    paths:
      - 'services/api/**'
      - 'docs/**'

jobs:
  sync-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Set up Python Environment
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install Dependencies
        run: |
          pip install -r services/api/requirements.txt

      - name: Generate OpenAPI Specification
        run: |
          python -c "import json; from services.api.main import app; print(json.dumps(app.openapi()))" > docs/openapi.json

      - name: Check for Spec Changes
        id: git-diff
        run: |
          git diff --quiet docs/openapi.json || echo "changed=true" >> $GITHUB_OUTPUT

      - name: Commit and Push Updated Spec
        if: steps.git-diff.outputs.changed == 'true'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add docs/openapi.json
          git commit -m "chore(docs): auto-update openapi.json from backend"
          git push origin main

      - name: Trigger Mintlify Deployment
        run: |
          curl -X POST https://api.mintlify.com/api/deploy \
            -H "Authorization: Bearer ${{ secrets.MINTLIFY_API_TOKEN }}"

マルチリポジトリ同期アーキテクチャ

バックエンドサービスが中央のドキュメントポータルとは別個のリポジトリに存在するマイクロサービスアーキテクチャでは、Repository Dispatch イベントまたは直接の API 呼び出しを使用します。

サービスの CI： バックエンドサービスが自身のリポジトリでビルドされる際、CI が openapi.json を生成します。
Dispatch または PR： ワークフローは GitHub パーソナルアクセストークンを使用してドキュメントリポジトリに Webhook イベントをディスパッチし、更新された仕様を含む自動 Pull Request を作成します。
検証とマージ： ドキュメントリポジトリはスキーマのリントを実行し、Mintlify プレビューを生成し、承認後に更新をマージします。

API ドキュメント自動化のベストプラクティス

成長するエンジニアリングチーム全体で高いドキュメント品質を維持するために、以下の運用標準を導入してください。

プラクティス	実装メカニズム	メリット
スキーマ検証	マージ前に CI で `mint validate` または Spectral リンターを実行する。	破損した OpenAPI スキーマや無効なパラメータ型が本番環境に混入するのを防ぐ。
アトミックなコード＆ドキュメント PR	API コードの変更と対応するドキュメント更新を同一の PR に含めることを義務付ける。	機能のデプロイとドキュメントの公開の間のタイムラグを解消する。
環境変数のセキュリティ	API キーや本番環境のシークレットを OpenAPI のサーバーブロックにコミットしない。	インタラクティブなプレイグラウンドでユーザーがテストキーを入力できるようにしつつ、インフラストラクチャを保護する。
エンドポイントのタグ付け	コード注釈で一貫した `tags` を使用して OpenAPI パスを整理する。	Mintlify はタグに基づいてエンドポイントを構造化されたナビゲーションセクションに自動的にグループ化する。
変更履歴の自動化	GitHub Releases または Git タグを使用して `docs/changelog.mdx` にリリースノートを生成する。	非推奨化、レートリミットの調整、新機能について利用者に常に最新情報を通知する。

API ドキュメントをコードとして扱い、ソースファイルを GitHub でホストし、デプロイおよび仕様パイプラインを自動化することで、ソフトウェアエンジニアリングチームはドキュメントの乖離（ドリフト）を排除し、開発者のオンボーディングを加速させ、すべてのリリースにおいて正確性を保つインタラクティブな API ポータルを提供できます。

ソフトウェアエンジニアリングチームが Mintlify と GitHub を使用して API ドキュメントを構築および自動化する方法

あなたの AI で 365 Wiki を使う

365Wiki Skill

Mintlify と GitHub による Docs-as-Code アーキテクチャの理解

ドキュメントリポジトリのセットアップ

1. リポジトリ構成

2. `mint.json` の設定

3. Mintlify CLI を使用したローカル開発

Mintlify GitHub App によるデプロイの自動化

インストールとブランチ設定

Pull Request プレビューとレビューゲート

GitHub Actions による OpenAPI 仕様更新の自動化

モノレポにおける仕様の同期

マルチリポジトリ同期アーキテクチャ

API ドキュメント自動化のベストプラクティス

ソフトウェアエンジニアリングチームが Mintlify と GitHub を使用して API ドキュメントを構築および自動化する方法

Mintlify と GitHub による Docs-as-Code アーキテクチャの理解

ドキュメントリポジトリのセットアップ

1. リポジトリ構成

2. mint.json の設定

3. Mintlify CLI を使用したローカル開発

Mintlify GitHub App によるデプロイの自動化

インストールとブランチ設定

Pull Request プレビューとレビューゲート

GitHub Actions による OpenAPI 仕様更新の自動化

モノレポにおける仕様の同期

マルチリポジトリ同期アーキテクチャ

API ドキュメント自動化のベストプラクティス

取り上げた製品

2. `mint.json` の設定