API 文件生成與維護

API 文件不是寫一次就完了——介面在變、參數在變、回傳值在變，文件卻經常滯後於程式碼。這個案例展示如何用 LanMate 從程式碼中提取介面定義，生成結構化 API 文件，並在介面變更時同步更新變更說明。

用到的技能

• 內建技能（隨 LanMate 安裝，開箱即用）：Word 文件（lanmate-docx）、HTML 報告（lanmate-html-report）
• 技能商店：技術文件寫作——指導技術內容的結構設計、程式碼範例編寫和受眾適配；Markdown 格式轉換器——Markdown 與 HTML 雙向轉換，支援表格、程式碼區塊等語法

場景痛點

• 文件和程式碼脫節：介面改了但文件沒更新，呼叫方踩坑才知道
• 介面定義散落各處：路由、參數、回傳值要翻多個檔案才能拼全
• 變更沒有記錄：哪個版本加了參數、哪個版本廢棄了介面，全靠口耳相傳
• 呼叫範例缺失：只有介面簽名，沒有可複製的請求 / 回應範例

推薦流程

提示詞範例

提取介面定義

請讀取 src/ 目錄下的程式碼檔案，提取所有 API 介面定義，整理為表格：
- 介面名稱和功能描述
- 請求路徑和方法（GET / POST / PUT / DELETE）
- 請求參數（名稱、型別、是否必填、說明）
- 回傳值結構（欄位名、型別、說明）
- 鑑權方式（Token / API Key / 無）
- 錯誤碼及含義

讀取程式碼中的介面定義、註解和型別宣告來提取資訊。
程式碼中未註解的功能描述，根據介面邏輯推斷並標註「（推斷）」。
輸出 Word 介面清單。

生成 API 文件

請根據提取的介面定義，生成一份完整的 API 文件，每個介面包含：
1. 介面概述：功能說明和適用場景
2. 請求格式：路徑、方法、請求標頭、請求參數表格
3. 請求範例：可複製的完整請求（含真實參數值）
4. 回應格式：回傳值結構表格
5. 回應範例：成功和失敗兩種回應
6. 錯誤碼表：錯誤碼、含義、處理建議

請求範例中的參數值使用合理的範例資料，不要用 "xxx" 或 "test" 占位。
輸出自包含 HTML 文件。

介面變更對比

請對比 src/ 目錄（目前版本）和 src-v1/ 目錄（上一版本）的程式碼，
識別 API 介面變更並分類：
- 新增介面：新出現的介面路徑
- 修改介面：參數、回傳值或行為有變化的介面
- 廢棄介面：已刪除或標記為廢棄的介面

每個變更輸出：
- 介面名稱和路徑
- 變更類型（新增 / 修改 / 廢棄）
- 變更詳情（改了什麼）
- 影響範圍（哪些呼叫方可能受影響）
- 遷移建議（修改類介面需要怎麼適配）

無法從程式碼差異確定影響範圍的，標註「待確認」，不要自行推測。
輸出 HTML 變更報告。

生成變更日誌

請根據介面變更對比結果，生成一份變更日誌，包含：
- 版本號和發布日期
- 變更摘要（新增 N 個介面、修改 M 個介面、廢棄 K 個介面）
- 逐條變更記錄（介面、變更類型、詳情、遷移建議）
- 不相容變更標記（需呼叫方立即適配的變更置頂）

廢棄介面需標註預計下線時間，程式碼中未標註的寫「待確認」。
輸出 Markdown 變更日誌，再用 Markdown 轉換器輸出 HTML 版本。

驗收標準

• 提取的介面定義與程式碼一致，推斷內容有標註
• API 文件每個介面含請求範例和回應範例，範例參數值合理可驗證
• 變更對比覆蓋所有介面變更，分類準確
• 變更日誌含遷移建議，不相容變更置頂
• 廢棄介面標註預計下線時間，未標註的寫「待確認」

常見錯誤