軟體工程團隊如何使用 Mintlify 與 GitHub 搭建並自動化 API 文件

軟體工程團隊經常難以讓 API 文檔與快速迭代的代碼庫保持同步，導致接口失效、參數缺失以及開發者體驗不佳。將 Mintlify 與 GitHub 結合採用文檔即代碼（docs-as-code）方法，使團隊能夠像對待應用程序代碼一樣，以同等的工程嚴謹度來管理文檔。透過將文檔文件直接託管在 Git 倉庫中、透過 Mintlify GitHub App 配置自動化部署，並將 OpenAPI 規範整合至持續整合（CI）流水線中，工程組織可以自動生成響應迅速的互動式開發者門戶。這種方案消除了手動更新文檔的負擔，確保 API 參考文檔與已部署的代碼完全一致，並透過 Pull Request 預覽建立流暢的審查工作流。

理解 Mintlify 與 GitHub 的文檔即代碼（Docs-as-Code）架構

Mintlify 基於文檔即代碼理念運行，文檔源文件存放在 GitHub 倉庫中，與生產代碼並存或相鄰。文檔不再依賴靜態內容管理系統（CMS）或獨立的 Wiki 軟體，而是使用 Markdown、MDX 組件和結構化配置文件進行定義。

該架構包含四個核心組件：

配置文件（mint.json）： 定義站點元數據、品牌標識、導航樹、搜尋設置以及與外部或內部 OpenAPI 規範連結的核心配置文件。
內容文件（.mdx）： 擴充 Markdown 文件，將標準文字格式與互動式 React 風格組件（例如參數表、分頁標籤、可折疊手風琴面板和代碼組）結合在一起。
OpenAPI 規範（openapi.json / openapi.yaml）： 標準化的機器可讀 REST API 描述，Mintlify 會解析它們以生成互動式端點參考文檔和「Try It」請求測試控制台。
Mintlify GitHub 整合： 原生 GitHub App，用於監聽倉庫 Webhook，在變更合併到生產分支時自動觸發雲端構建，並為 Pull Request 生成預覽環境。

+-----------------------------------------------------------------------+
|                           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，也可以在現有的應用程序單體倉庫（Monorepo）中實現。從清晰的目錄結構開始，可以確保直觀的導航和清晰的 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 都會觸發生產構建。
如果文檔位於 Monorepo 的子目錄中（例如 /docs），請啟用子目錄開關並指定路徑。這將限制構建，使 Mintlify 僅在文檔目錄內的文件發生更改時才觸發。

Pull Request 預覽與審查門禁

當工程師發起修改文檔文件的 Pull Request 時，GitHub App 會自動執行構建檢查，並在 PR 中留言附上唯一的預覽 URL：

視覺品質保證（Visual QA）： 審查人員可以在合併前直接在預覽網域上檢查渲染出的 MDX 組件、格式和互動式測試控制台。
語法驗證： 如果引入了格式錯誤的 Markdown 元素、失效的內部連結或無效的 JSON 模式，構建檢查將會失敗，從而阻止 PR 合併到 main 分支。
跨職能協作： 技術文檔工程師、產品經理和開發人員可以在用於代碼審查的同一界面中審查文案修改。

透過 GitHub Actions 自動化更新 OpenAPI 規範

概念指南通常使用 MDX 手動編寫，而 API 參考文檔則應始終直接派生自源代碼。當後端工程師修改接口路由、請求負載或響應模式時，自動化流水線必須更新文檔目錄中的 OpenAPI 規範文件。

在單體倉庫（Monorepo）中同步規範

在 API 服務代碼（例如 FastAPI、Express、NestJS 或 Go）與文檔並存的 Monorepo 中，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 Personal Access Token 向文檔倉庫派發 Webhook 事件，以更新後的規範發起自動化 Pull Request。
驗證與合併： 文檔倉庫運行模式 Lint 檢查，生成 Mintlify 預覽，並在獲得批准後合併更新。

API 文檔自動化最佳實踐

為了在不斷擴大的工程團隊中保持高標準的文檔品質，建議執行以下運維標準：

實踐	實施機制	效益
模式驗證	在合併前於 CI 中運行 `mint validate` 或 Spectral Linter。	防止損壞的 OpenAPI 模式或無效的參數類型進入生產環境。
原子化代碼與文檔 PR	要求 API 代碼變更與對應的文檔更新包含在同一個 PR 中。	消除發布功能與發布其對應文檔之間的時間差。
環境變數安全	切勿將 API 金鑰或生產機密提交到 OpenAPI 伺服器配置塊中。	保護基礎設施安全，同時允許使用者在互動式測試控制台中輸入測試金鑰。
端點標籤（Tagging）	在代碼註解中透過一致的 `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 規範

在單體倉庫（Monorepo）中同步規範

多倉庫同步架構

API 文檔自動化最佳實踐

軟體工程團隊如何使用 Mintlify 與 GitHub 搭建並自動化 API 文件

理解 Mintlify 與 GitHub 的文檔即代碼（Docs-as-Code）架構

搭建文檔代碼庫

1. 倉庫結構

2. 配置 mint.json

3. 使用 Mintlify CLI 進行本地開發

透過 Mintlify GitHub App 實現自動化部署

安裝與分支配置

Pull Request 預覽與審查門禁

透過 GitHub Actions 自動化更新 OpenAPI 規範

在單體倉庫（Monorepo）中同步規範

多倉庫同步架構

API 文檔自動化最佳實踐

涉及產品

2. 配置 `mint.json`