This article is not yet available in English. You are reading the Traditional Chinese original. The English edition will appear here once it is translated.
Browse articles that do have an English editionAPI 文檔同步更新系統：從人工維護到代碼驅動的文檔自動化
後端工程師改了一個 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 合規與風險邊界
- 流程越串越多、要不要升級成平台：自建還是採購