後端工程師改了一個 API 的請求參數，忘記更新 Swagger 文件；前端同事照舊文件呼叫，收到 400 錯誤，花兩小時除錯才發現是文件過期。這類「文檔不同步」是跨團隊協作最常見的摩擦點：慢、容易誤解、而且品質取決於當天誰記得更新。這篇是操作配方：用 Apidog、Fern、Mintlify 與 LLM 節點串出一條文檔同步流水線，讓機器從程式碼自動提取介面定義、生成示例、檢測不一致，人只處理需要業務語境補充的部分。全文最重要的一節是第五節——哪些環節可以從程式碼自動提取，哪些環節必須由人補充業務語境，這條邊界畫錯了，自動化會比人工更危險。
這個場景解決什麼
適合這個配方的流程有四種特徵：高頻率（每週都有 API 變更）、跨團隊（前後端、第三方整合都需要文件）、規則說得清楚（OpenAPI 規範、註解格式）、繁瑣但必須做。四者俱備的人工維護，通常有三種損耗：延遲（改完 code 忘了改 docs）、不一致（文件與實作脫節）、不完整（缺少示例或錯誤碼說明）。
做完這個配方之後的目標狀態：API 變更觸發自動文檔更新，不一致之處被標記並推到人面前，附帶結構化的待補清單。人的角色從「手動寫整份文件」變成「審核自動生成的內容並補充業務語境」。
同時畫清邊界：這篇處理的是技術介面的文檔化，不是要你用 AI 撰寫產品說明書；需要業務邏輯解釋與使用場景描述的環節（例如「為什麼要這樣設計」、「適用什麼業務情境」）也不在自動化範圍內。判斷一個場景值不值得自動化，先讀什麼時候不該用 AI。
工具組合與前置準備
- Apidog：一體化的 API 開發平台，整合 API 設計、模擬、測試、文檔生成。支援從程式碼註解自動提取 OpenAPI 規範，並提供可互動的 API 測試介面。優點是全流程整合；缺點是鎖定單一平台。方案與定價以官網為準。
- Fern：開源優先的 API 文檔生成器，從 OpenAPI/Swagger 規範生成美觀、可搜索的文檔網站，支援多語言 SDK 自動生成。優點是輸出品質高、易客製化；缺點是需要額外部署。GitHub 上有活躍的開源社群。
- Mintlify：專為開發者體驗優化的文檔平台，基於 Next.js，支援 Markdown/MDX，內建搜索、暗黑模式、版本控制。優點是開發者友好、SEO 友好；缺點是需要學習其內容結構。定價以官網為準。
- LLM API（本文以 DeepSeek 為例，任何供應商皆可）：負責流程中「自然語言生成」與「語義補充」的判斷。單價以供應商官網為準；接通後第一件事是在供應商控制台設定花費上限與用量告警。
前置檢查表——每一項都有明確答案才動工：
| 檢查項 | 要確認什麼 | 沒確認就做的後果 |
|---|---|---|
| 程式碼註解規範 | 團隊是否有統一的 API 註解格式（如 JSDoc、Swagger annotations） | 自動提取失敗或提取出不完整的資訊 |
| 倉庫權限 | CI/CD 帳號是否有讀取程式碼、寫入文檔倉庫的權限 | 流程跑完但無法更新文檔 |
| 資料分級 | API 是否包含敏感端點（內部管理、金流）；能否公開文檔 | 敏感 API 細節洩露，資安事故 |
| 維運責任 | 上線後誰審核自動生成的文檔、誰調整提取規則 | 錯誤文檔上線，比沒有文檔更糟 |
資料分級的判斷方法見企業資料安全基本盤。
憑證紀律（先講，因為最常被忽略）：所有 API Key、Deploy Token 放進 CI/CD 平台的 secrets 機制；不要寫死在 workflow 檔案、註解或說明文件裡；不要把含憑證的配置檔提交到公開倉庫。
一、盤點人工文檔痛點
花兩週，把所有 API 文檔維護中的常見問題列成一張表：
| 問題類型 | 發生頻率 | 平均發現時間 | 修復成本 | 現在誰發現 |
|---|---|---|---|---|
| 參數變更未更新文件 | 每週 2-3 次 | 前端測試時 | 中（需協調雙方） | 前端工程師 |
| 缺少請求示例 | 每次新 API | 開發者首次使用 | 低（但影響體驗） | 外部整合夥伴 |
| 錯誤碼說明不完整 | 每月 1-2 次 | 生產環境報錯 | 高（需緊急修復） | 客服團隊 |
| 文檔與實作不一致 | 每週 1-2 次 | 集成測試階段 | 中（需重新對齊） | QA 工程師 |
兩個填寫紀律：頻率與成本是從實際 issue tracker 與 git log 統計出來的，不靠印象——口頭回憶幾乎總是低估；修復成本要寫具體事件（哪次整合延遲、花了多少人天），寫不出成本的問題，說明它可能根本不值得優先自動化。
這張表有兩個用途：下一步的選型依據，以及上線後計算效益的基線。「自動化前平均每筆 API 變更文檔維護多久、自動化後例外處理要多久」都從這張表與後面的執行紀錄算出來——自己測的數字，比任何文章裡的參考值可靠。
二、選一條最痛的 API 流程
四個條件同時成立才動手：頻率高（經常變更）、規則寫得出來（有標準註解格式）、出錯有代價（影響跨團隊協作）、工具鏈有介面。
兩類流程先避開：內部實驗性 API（變動太快，文檔追不上）；無程式碼註解的 legacy API（需要先補註解，工作量過大）。
第一版切小：只做「程式碼變更 → 提取 OpenAPI 規範 → 生成文檔草稿 → LLM 補充示例 → 不一致檢測 → 文檔發布」這一條主幹。多版本管理、SDK 自動生成全留到第二版。一條穩定跑通的主幹，勝過一張完整但沒上線的設計圖。
三、自架還是雲端
| 考量點 | 自架 | 官方雲端 |
|---|---|---|
| 資料位置 | 文檔與程式碼在自己環境，適合分級要求高的專案 | 文檔經供應商環境，須先過資料分級這一關 |
| 維護責任 | 升級、擴展、停機處置都是你的 | 供應商負責 |
| 起步速度 | 需要伺服器資源與基本 DevOps 能力 | 註冊即用，幾分鐘內完成整合 |
| 預算形態 | 伺服器費用加維運人力 | 訂閱制，金額以官網為準 |
決策方法：資料分級結果說「不能出網」時，自架 Fern 或 Mintlify 幾乎是唯一選項；否則先用 Apidog 或 Mintlify Cloud 把第一條流程跑通，累積了真實用量與失敗紀錄，再評估要不要遷移。不論哪種，都先用測試分支跑通示範流程，第一天不碰生產倉庫。
四、串出最小可跑版本
節點組裝順序：
- 觸發節點：GitHub Actions 的
push事件觸發（監聽特定路徑如src/api/**）。優先事件型觸發，退而求其次才用定時輪詢。 - 提取節點：執行程式碼掃描工具（如 swagger-jsdoc、drf-spectacular、springdoc-openapi），從註解提取 OpenAPI 規範 JSON/YAML。
- 驗證節點：使用
openapi-validator檢查生成的規範是否符合 OpenAPI 3.0/3.1 標準，確保語法正確。 - LLM 補充節點：將 OpenAPI 規範送入 LLM，要求生成請求示例、常見錯誤場景說明、業務語境補充。
- 不一致檢測節點：比對新生成的規範與現有文檔，標記差異點（新增端點、刪除端點、參數變更）。
- 文檔生成節點：使用 Fern 或 Mintlify 將規範轉換為美觀的文檔網站，部署到預覽環境。
- 審核通知節點：將差異報告與預覽連結發送給負責的工程師，要求審核並合併。
試跑期三條紀律：
- 用測試分支：建立
feature/test-api-change分支，故意修改一個 API 參數，驗證工具能否正確提取並檢測到變更。 - 留執行紀錄：除平台內建的執行歷史外，為重要流程加一個「台帳」分支——每次執行把時間、API 路徑、變更類型、檢測到的差異寫進一張專用表格或資料庫。這是第八節監控的原料。
- 影子模式上線：自動化先生成文檔但不發布，人照樣手動維護，逐日比對兩邊結果。連續一致之後才讓自動化接管發布，人轉為審核。
五、哪些環節交給自動提取、哪些必須用人補充
這是全文最重要的一節。原則一句話：確定性的介面定義給自動提取工具，LLM 只做「示例生成」與「語義補充」這一類需要創造性的事。
| 環節 | 用什麼 | 為什麼 |
|---|---|---|
| 端點路徑、HTTP 方法、參數定義 | 從程式碼註解自動提取 | 同樣輸入必須同樣輸出；這些是確定性資訊，LLM 做不到這個保證 |
| 資料類型、必填欄位、預設值 | 從程式碼註解自動提取 | 基於 AST 或正則的模式匹配，準確率高且可解釋 |
| 請求示例、回應示例 | LLM 節點 | 需要根據參數定義生成合理的假資料，這是 LLM 的強項 |
| 錯誤碼說明、業務語境 | LLM 節點＋人工審核 | LLM 能生成通用說明，但業務特定邏輯需人補充 |
| 端點之間的依賴關係 | LLM 節點＋呼叫圖分析 | 需要理解業務流程，靜態分析只能給出部分答案 |
| 文檔的自然語言表達 | LLM 節點 | 但端點路徑、參數名稱由自動提取工具原樣注入，LLM 不得改寫任何技術細節 |
兩條鐵律：
- 技術細節永遠不經過 LLM 的嘴。 端點路徑、參數名稱、資料類型由自動提取工具原樣提取；LLM 只產示例與說明，不產事實。自動化文檔裡代價最高的事故，形態幾乎都是「模型改寫了一個參數名稱，而且改得很像真的」。
- LLM 輸出永遠當作不可信輸入。 LLM 節點要求輸出固定結構的 JSON（欄位在提示詞裡逐一列舉）；下游第一個節點做格式校驗，校驗不過直接進例外分支，不允許「盡量解析」。
LLM 節點的提示詞寫法：給示例生成規則（「使用真實感強的假資料，避免 foo/bar」）、給輸出 JSON 的欄位定義、給邊界規則（「只根據提供的 OpenAPI 規範生成示例，不 invent 新的端點」），溫度調低以減少隨機性。提示詞不神奇，神奇的是它後面接了校驗節點。
以下是一個典型的 LLM 示例生成提示詞範例：
你是一位資深 API 文檔工程師，負責為以下 OpenAPI 端點生成請求與回應示例。
【端點定義】
{{endpoint_definition}}
【生成規則】
- 使用真實感強的假資料（如 "john.doe@example.com"、"2024-01-15T10:30:00Z"）
- 避免使用 foo、bar、test 等無意義的值
- 字符串示例需符合欄位描述中的格式要求（如 email、date-time）
- 數值示例需在合理範圍內（如年齡 18-65、金額 10-1000）
- 布林值示例需根據欄位名稱選擇合理的 true/false
【輸出格式】
請嚴格按照以下 JSON 格式輸出，不要添加任何其他文字：
{
"request_example": {
"headers": object,
"query_params": object,
"body": object
},
"response_examples": [
{
"status_code": number,
"description": string,
"body": object
}
],
"error_scenarios": [
{
"status_code": number,
"error_code": string,
"message": string,
"cause": string
}
]
}
【邊界規則】
- 只根據提供的端點定義生成示例，不 invent 新的欄位
- 如果端點定義不完整，在輸出中标記 "incomplete_definition"
- 不要改寫任何端點路徑或參數名稱
六、錯誤處理、重試與冪等
先把失敗分成三類，因為三類的處置完全不同：
| 失敗類型 | 例子 | 處置 |
|---|---|---|
| 暫時性 | API 限流、網路逾時 | 節點自動重試（設次數與間隔）；重試耗盡仍失敗進例外分支 |
| 資料性 | 註解格式錯誤、OpenAPI 規範驗證失敗、LLM 輸出格式錯誤 | 不重試（重試還是錯）；直接進例外分支，人修註解後重跑 |
| 設定性 | Deploy Token 過期、文檔平台服務停機、倉庫權限不足 | 立即停止流程並告警，等人介入 |
冪等是重試的前提：流程要保證「同一個 API 變更跑兩次不會重複生成文檔」。做法是在生成文檔前先查詢該版本是否已存在——存在就跳過或更新，絕不無腦新增。沒有冪等設計就開重試，等於裝了一台文檔製造機：重複的版本歷史，比人工維護還難收拾。
七、失敗告警
- 告警發到「有人在值班」的渠道：即時通訊群組或 email，且群組裡有明確的值班表。告警沒人看，等於沒有告警。
- 告警內容模板：流程名稱、API 路徑、失敗節點、錯誤摘要、發生時間、重跑方式。讓收到的人在半分鐘內能決定「現在處理還是稍後處理」。
- 分級防洗版：單筆 API 文檔生成例外進每日匯總；Deploy Token 過期、服務停機這類「流程已停」的事件才即時推送。每筆例外都彈一次通知，值班的人很快會把渠道靜音——告警系統就死在靜音那一刻。
八、上線後的監控
- 前兩週是觀察期：每天看執行歷史與台帳，記錄執行總數、失敗次數、誤報率（人工標記為不準確的示例比例）。兩週之後自己算誤報率與主因分佈——這是你的流程自己的數據，判斷門檻（誤報率高到多少要調整提示詞）由你的團隊容忍度決定，定了就寫進值班說明，不要引用任何文章裡的現成數字。
- 每週抽樣複核：固定抽 5-10 個已自動生成的端點文檔，人工複查示例是否合理、說明是否清晰。抽樣筆數依 API 量自定，關鍵是固定頻率、留下紀錄、發現問題就調整規則或提示詞。抽樣抓的是「流程沒報錯但生成了不合理示例」這類最安靜的事故。
- 變更紀律：團隊註解規範更新、LLM 供應商更新模型版本、你改提示詞，都算變更。改動前先用最近的例外樣本與幾筆正常樣本重跑一遍，確認沒有變差再上；改動寫進台帳。
- 成本：LLM 節點的用量乘上供應官網單價，加上文檔平台授權費與你的維運時間，就是這條流程的真實成本；估算方法見AI 成本怎麼算。
成果與驗收標準
| 檢查點 | 通過標準 | 沒通過怎麼辦 |
|---|---|---|
| 盤點基線 | 有文檔痛點表，頻率與成本是從 issue tracker 統計的紀錄 | 回到第一節；先別急著搭流程 |
| 主幹跑通 | 測試分支端到端跑完，檢測到故意放入的變更 | 檢查註解格式與權限 |
| 確定性邊界 | 端點路徑、參數名稱沒有任何一個由 LLM 改寫 | 改成自動提取工具直接提取 |
| LLM 輸出校驗 | LLM 輸出有格式校驗節點，不合法進例外分支 | 在 LLM 節點後補校驗 |
| 冪等 | 手動觸發同一個 API 變更兩次，沒有重複文檔版本 | 加版本存在性檢查 |
| 影子期 | 與人工並行連續數日結果一致才交接 | 延長影子期，逐項找不一致的原因 |
| 告警有效 | 故意製造一次失敗（暫撤測試 Deploy Token），告警在承諾時間內到達值班渠道且內容完整 | 修告警路由與值班安排 |
| 監控習慣 | 台帳連續兩週每週有紀錄，抽樣複核有留痕 | 把監控指派到具體的人，放進行事曆 |
常見踩坑
- 讓 LLM 做確定性工作：「讓 AI 順便提取一下參數」一時方便，代價是同樣輸入可能不同輸出，出了錯無法重現、無從追查。
- 用個人帳號的憑證：當事人離職、改密碼的那天，流程集體猝死。用服務帳號，並納入組織的憑證管理。
- 直接在生產倉庫上實驗：正確順序是測試分支、非敏感 API 小範圍、全量。跳級的人通常在第二步就出事。
- 沒做冪等就開重試：重試機制會把偶發錯誤放大成重複文檔事故。
- LLM 節點不設花費上限：一個迴圈觸發的臭蟲能讓流程整夜持續呼叫 API。上限與告警在供應商控制台設定，五分鐘的事。
- 告警發到沒人看的渠道：沒有值班表的告警是自我安慰。
- 忽略註解品質：自動化提取的前提是程式碼中有完整且一致的註解。如果團隊尚未建立註解規範，先花時間統一規範，否則自動化只會提取出垃圾。
- 一次性生成所有 API 文檔：一週把上百個端點全部自動化，第二週就沒有人力調整誤報。先讓核心 API（最高頻使用的 10-20 個端點）穩定跑滿一個月，把模式沉澱成範本，再複製到其他端點。
下一步
- 同一套「自動提取＋人工審核」模式用在代碼審查場景：自動化代碼審查助手
- 技術債的量化與優先級排序：技術債追蹤與重構優先級排序
- CI/CD 管道的異常檢測：CI/CD 管道異常檢測與修復建議
- 微服務架構的依賴可視化：微服務依賴關係地圖生成
- 資料分級與安全邊界：企業資料安全基本盤
- 上線前的合規檢查表：AI 合規與風險邊界
- 流程越串越多、要不要升級成平台：自建還是採購