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 文件每個介面含請求範例同回應範例，範例參數值合理可驗證
• 變更對比覆蓋所有介面變更，分類準確
• 變更日誌含遷移建議，不相容變更置頂
• 廢棄介面標註預計下線時間，未標註嘅寫「待確認」

常見錯誤