用 Claude Code 維護 API 文件：規格、型別同範例一齊更新

文件點解成日追唔上程式？

假設訂單 API 加咗新欄位，後端已經用緊，前端型別同文件範例仲係舊版。Claude Code 可以幫你搵出差異，但單靠一句「同步所有文件」，唔會建立長期可靠嘅流程。

先揀一份權威定義，再由工具產生其他檔案。例如以 Zod 結構定義配合路由資料產生 OpenAPI，再由 OpenAPI 產生 TypeScript 型別。範例則由受控測試資料產生，最後用程式驗證。Claude 負責整理改動同解釋差異。

1. 先確認邊份資料先作準

呢段 Hono 風格嘅程式只示範請求驗證：

app.post('/api/orders', async (c) => {
  const body = CreateOrderSchema.parse(await c.req.json())
  const order = await createOrder(body)
  return c.json({ success: true, data: order })
})

有 CreateOrderSchema，唔代表已經有完整 OpenAPI。你仲要定義路徑、HTTP 方法、成功同失敗狀態碼、回應結構、驗證方式。尤其上面回應有 success 同 data 包住，唔可以直接將 Order 當成整個回應。

讀取訂單路由、請求與回應驗證、現有 OpenAPI 產生器同相關測試。

請列出每一層以邊份檔案作準，指出未有定義嘅錯誤回應、狀態碼及權限要求。先提出同步方案，唔好自行改 API 行為或新增依賴。

如果已有產生工具，沿用現有工具。唔好靠模型由程式猜出一份規格，再當成已驗證答案。

如果專案用 Zod，可以評估 @asteasolutions/zod-to-openapi；先核對佢支援你目前嘅 Zod 版本。套件只係其中一部分，路由註冊同產生指令仍要由專案實作。

2. 由規格產生型別

以下假設專案已經有正確嘅 openapi.yaml，並安裝咗 openapi-typescript。統一用專案本身嘅套件管理器，唔好同時產生幾份鎖定檔。

{
  "scripts": {
    "gen:types": "openapi-typescript openapi.yaml -o src/types/api.ts"
  }
}

pnpm gen:types

前端可以從產生嘅型別取出請求內容，唔使人手再抄一次欄位：

import type { paths } from '@/types/api'
type CreateOrderBody = paths['/api/orders']['post']['requestBody']['content']['application/json']

實際型別結構取決於規格，例如請求內容可選時，索引寫法亦要調整。產生之後仍要跑 TypeScript 檢查；型別通過唔等於伺服器實際回應符合規格。

3. 範例要由測試資料產生

唔好寫一條程式遍歷所有 OpenAPI 路徑，再向測試環境發送所有請求。paths 係物件，唔係包含 path、method 嘅陣列；而且 POST、DELETE 等操作可能改資料、發通知，甚至呼叫外部服務。

較穩陣嘅做法係列明允許收集嘅案例：測試名稱、路徑、預期狀態碼、測試資料、回應檔名。喺獨立測試環境準備資料，用已遮蓋個人資料嘅結果更新文件。

為 GET /api/orders/:id 加一個整合測試，用固定測試訂單，唔好讀取真實客戶資料。

核對 HTTP 狀態碼、Content-Type 同 OpenAPI 回應結構。唔符合就令測試失敗，唔好覆寫現有範例。成功先將已去除時間戳、隨機 ID 等不穩定值嘅回應儲存。

說明使用嘅驗證工具係咪支援目前 OpenAPI 版本。指出規格容許額外欄位、可選欄位同空值嘅情況，唔好將所有額外欄位一律判錯。

Claude 可以解釋驗證報告，但精確嘅結構核對應由驗證器負責。範例通過只證明該案例符合規格，唔代表所有可能輸入都已覆蓋。

4. 將流程放入日常開發

喺 CLAUDE.md 寫低「改路由時要執行邊幾條現有指令」，再將重複步驟整理成 skill。以下係指示內容，入面嘅產生指令要先喺專案建立：

---
name: api-doc
description: 更新 API 規格、型別同測試範例
disable-model-invocation: true
---

先讀今次路由改動及相關測試。
1. 執行專案已有嘅規格產生指令。
2. 執行 pnpm gen:types。
3. 執行指定 API 合約測試及範例檢查。
4. 覆檢規格、型別、範例差異，列出相容性影響。
5. 保留改動畀人審閱，唔好自行提交或部署。

可以放喺 .claude/skills/api-doc/SKILL.md。舊 .claude/commands/ 格式仍受支援，新流程可按官方 skills 文件整理。

CI 要喺乾淨 checkout 重新產生檔案，再檢查有冇差異。專案如果要求通過先合併，就要將該項檢查設成必要條件；本機 pre-commit hook 可以略過，單靠佢唔足夠。產生器版本、排序同格式亦要固定，避免同一份來源每次都產生唔同結果。

換技術時，保留同一條原則

FastAPI 可以提供 OpenAPI 文件；GraphQL 通常以 schema 配合型別產生器；Webhook 則要記錄事件內容、簽署驗證、重試同接收方回應要求，未必需要另加 AsyncAPI。

無論用邊套工具，都要保留一個獨立驗證：規格改咗，實際行為有冇跟？如果來源本身寫錯，自動產生只會將同一個錯誤複製去幾層。審閱請求與回應定義，同檢查產生結果一樣重要。