用 AI 寫 API 文件：把程式碼丟給 AI，產出清楚端點說明、範例請求與錯誤碼

一分鐘重點：API 文件之所以永遠對不上程式碼，不是工程師懶，是寫文件的成本太高、又排在功能後面。AI 能把這件事的成本砍掉八成——你把路由、參數、回傳結構貼給它，它就能生出端點說明、curl 範例與錯誤碼表。但 AI 有個致命習慣：它會補出「看起來很合理但根本不存在」的參數。所以真正的工作流是「AI 產草稿 → 你對照程式碼驗證 → 納入版控」，少了中間那步，你只是把錯誤文件產得更快而已。

這篇要解決的問題：教你一套把程式碼交給 AI、產出可對外的 API 文件、並維持與程式碼同步的完整方法。 適合誰讀：後端工程師、需要維護串接文件的技術寫作者、要開放 API 給外部的 SaaS 團隊、寫內部服務怕沒人看得懂的人。 讀完你會得到：一套餵程式碼的層次原則、可複製的文件生成 Prompt 範本、端點說明表與 curl 範例的標準長相，以及一份「別讓文件說謊」的驗證清單。

為什麼 API 文件永遠比程式碼慢半拍

先講一個大家都遇過的場景。後端趕在 sprint 結束前把新端點合併進 main，功能測過、能跑，收工。文件呢？「之後補」。結果三週後前端來問：「這個 status 欄位有哪些值？」後端自己翻程式碼翻了十分鐘。又過一個月，外部客戶串接，回報「你們文件寫的 page_size 最大 100，但我丟 200 也會過」——因為程式碼後來改過，文件沒動。

問題的根不在態度，在結構。文件與程式碼是兩份各自維護的東西，改一邊不會強迫你改另一邊，於是它們必然漂移。傳統解法是「紀律」：要求每次改 API 就更新文件。但紀律在趕工時第一個被犧牲。

AI 改變的是這個等式裡的「成本」。過去補一份端點文件、想範例、列錯誤碼，可能要半小時；現在把程式碼貼上、一個 Prompt，三分鐘拿到草稿。當補文件的成本從半小時降到三分鐘，它就有機會被塞回 PR 流程裡，而不是永遠躺在待辦清單最底下。

但要注意：AI 降低的是「把程式碼翻成文件」的成本，沒有降低「確認文件是對的」的成本。後面這件事還是你的責任。

核心原則：餵給 AI 越接近「真相來源」的程式碼，文件越準

寫 API 文件時，最容易犯的錯是用「口述」餵 AI：「我有一個查訂單的 API，可以帶時間區間跟狀態篩選。」AI 只能照這句話補，補出來的參數名稱、型別、預設值全是它猜的，跟你程式碼裡真實的 order_status、created_after 八成對不上。

正確做法是餵決定 API 實際行為的那幾層程式碼，由近到遠：

• 路由定義（Express router、FastAPI decorator、Laravel routes、Spring @RequestMapping）——決定路徑與 HTTP 方法。
• 請求與回應的結構（DTO、TypeScript interface、zod／pydantic／Joi schema）——決定參數與回傳長相。
• 驗證規則（validator、middleware）——決定哪些是必填、範圍限制、格式。
• controller／handler 主體——決定各種分支會回什麼狀態碼。

這幾層是 API 的「真相來源」。AI 從這裡推斷，等於在讀程式碼，而不是讀你的記憶。你貼得越完整，它亂編的空間越小。

一個實務提醒：貼之前先把機敏資訊清掉。內部註解、環境變數、資料庫連線字串、還沒對外的實驗欄位，都不該進入對外文件。AI 不會替你判斷什麼該藏，你貼什麼它就用什麼。

可複製的文件生成 Prompt 範本

下面這段直接複製，把中括號換成你的東西。它的重點是：強制 AI 標出「哪些是它從程式碼確認的、哪些是它猜的」，這是防止 hallucination 最有效的一招。

你是一位資深後端工程師兼技術文件寫手，正在為外部串接的工程師撰寫 API 文件。

【技術棧】
語言與框架：[例如 Node.js + Express / Python + FastAPI / PHP + Laravel]
文件格式：[Markdown 表格 / OpenAPI 3.1 YAML / 內部 wiki]
讀者：[外部串接工程師 / 公司內部同事]

【以下是真實程式碼，請只根據它推斷 API 行為，不要自行補充程式碼裡沒有的欄位】
路由定義：
[貼上 router / route 定義]

請求與回應結構：
[貼上 DTO / interface / schema]

驗證規則：
[貼上 validator / middleware，若無則寫「無」]

【請產出以下內容】
1. 端點總覽表：方法、路徑、用途，一行一個。
2. 每個端點的詳細說明，含：
   - 路徑參數、Query 參數、Request Body 欄位表（欄位名、型別、必填與否、說明、範例值）
   - 一個可直接複製的 curl 範例
   - 一個成功回應的 JSON 範例
   - 至少一個失敗情境的 JSON 範例
3. 錯誤碼表：狀態碼、觸發條件、錯誤訊息。

【重要規則】
- 只記錄程式碼裡真實存在的欄位與行為，不要憑常見寫法補參數。
- 凡是你「無法從我提供的程式碼確認」的欄位、預設值或錯誤情境，請在該處標上「⚠️ 待工程師確認」，不要自己填。
- 只記錄對外公開欄位，若程式碼裡有明顯的內部欄位，請單獨列出並標為「內部用，不對外」。
- 用繁體中文台灣用語撰寫說明，欄位名與程式碼術語保留原文。

這個範本的靈魂在最後那組規則。少了「⚠️ 待工程師確認」這條，AI 會把不確定的地方用最像樣的猜測填滿，而那些猜測正是之後坑客戶的地雷。逼它把不確定攤開來，你才知道哪裡要回頭查。

文件長什麼樣：端點說明表與 curl 範例

給 AI 一個明確的產出格式，比讓它自由發揮好太多。下面是可以要求它照抄的標準骨架。

端點總覽：

單一端點的參數表：

範例請求（curl）：

curl -X GET "https://api.example.com/api/v1/orders?status=paid&page_size=50" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

成功回應（200）：

{
  "data": [
    { "id": "ord_1029", "status": "paid", "total": 1280, "created_at": "2026-06-30T08:12:00Z" }
  ],
  "pagination": { "page": 1, "page_size": 50, "total": 137 }
}

錯誤碼表：

這種結構的好處是，讀者掃一眼就知道怎麼打、會拿到什麼、出錯長怎樣。而且它對 AI 很友善——你把骨架給它，它填內容，不會每個端點格式都不一樣。

台灣團隊實戰：一份漂移兩年的文件怎麼救回來

台北一家做電商 SaaS 的團隊「初芽科技」，對外開放訂單與物流 API 給合作店家串接。他們的痛點很典型：文件放在 Notion，最後更新是兩年前，程式碼早改了七八輪。工程主管陳彥豪自己算過，客服每個月接到的串接問題有一半是「文件跟實際不一樣」，光來回釐清就吃掉一位工程師大半天。

他們沒有一次重寫全部，而是分三步。第一步，讓後端把每個對外端點的 router、DTO 與 validator 貼進上面那套 Prompt，用 Claude 產出草稿，格式統一成端點表加 curl 範例。四十幾個端點，兩天生完草稿。

第二步是關鍵——驗證。他們沒有直接發布，而是寫了一個小腳本，拿 AI 產出的 curl 範例實際打測試環境，比對回應結構。這一輪抓出三類問題：AI 把一個其實已經淘汰的 sort_by 參數寫進去了（它從舊註解推斷的）；有兩個端點的錯誤碼 AI 只列了 400 和 500，漏了實際會回的 422；還有一個分頁欄位 AI 猜成 limit，程式碼裡其實叫 page_size。這些全是「看起來很對」的錯，沒實際打過根本抓不到。

第三步，把驗證過的文件搬進能從 OpenAPI 生成的 Redoc 頁面，並在 PR 模板加一行 checklist：「本次是否更動 API？若是，是否已更新對應 spec？」

三個月後回頭看，客服的串接類問題掉了約六成，合作店家串接上線的平均時間從兩週縮到五天。陳彥豪的結論很實在：「AI 幫我們把兩年的債一週還完，但要不是我們堅持每條 curl 都真的打過，我們只是把錯誤抄得更整齊。」

常見錯誤與限制：別讓文件比沒有更糟

用 AI 寫 API 文件，最危險的不是產不出東西，是產出「錯得很有說服力」的東西。以下幾個坑務必記住。

AI 會憑空編參數。 這是最常見也最傷的。它讀了幾萬個 API 的寫法，看到你有查詢端點，就「幫你」補上 sort、order、limit 這種常見參數——即使你程式碼裡根本沒有。錯誤文件比沒有文件更糟，因為讀者會信。破解法只有一條：對照真實程式碼，逐項確認每個欄位存在。

文件與程式碼脫節是預設狀態，不是意外。 只要文件跟程式碼是兩份分開維護的東西，它們就會漂移。能自動生成就自動生成（OpenAPI 註解、schema-first），AI 負責把生成物補成人話。做不到自動化，就要靠流程綁死——把更新文件塞進 PR checklist，並定期用 AI 做一次「拿最新程式碼比對現有文件、列出差異」的稽核。

缺錯誤情境是新手最容易漏的一塊。 多數人請 AI 寫文件只想到「成功長怎樣」，但串接工程師花最多時間的是處理失敗。哪些狀態碼、什麼條件觸發、訊息長怎樣、要不要重試——這些沒寫清楚，對方就得靠猜。Prompt 裡一定要明確要求列出所有錯誤情境，並自己補上 AI 從程式碼看不出來的業務邏輯錯誤。

機敏資訊會照抄進文件。 AI 不會判斷什麼該對外、什麼是內部欄位。你貼含有內部欄位或註解的程式碼，它可能原封不動寫進公開文件。貼之前先清，Prompt 裡也要求它把疑似內部的欄位單獨標出。

限制講白：AI 沒跑過你的 API。 它是靠讀程式碼推理，不是靠實際呼叫。任何牽涉執行期行為的東西——實際的回應範例值、真正會觸發的錯誤、效能相關的限制——都必須用實際打一次 API 來確認。把「AI 產草稿、人打 API 驗證」當成不可拆的一組動作，你的文件才真的可信。

動手做：先救一個最常被問的端點

不用一次重寫整份文件。挑你團隊裡「客戶問最多、最容易踩雷」的那一個端點，把它的 router、DTO、validator 貼進上面的 Prompt 範本，讓 AI 產出端點表、curl 範例與錯誤碼表。然後——這步別跳——拿產出的 curl 實際打一次，逐欄對照程式碼，修掉 AI 亂編的參數，補上它標為「待確認」的地方。跑完這一輪，你會很清楚 AI 幫你省了多少、又有哪些非你把關不可。接著把這套流程複製到下一個端點，並想辦法把「改 API 就更新文件」綁進你的 PR 流程，讓文件從此不再漂移。

更多把 AI 接進開發流程的實戰方法，都收在 AgentAI 智庫（agentai.tw）——台灣最大的繁體中文 AI 知識站。想先練好餵程式碼的基本功，接著讀〈寫程式的 Prompt 技巧〉。

常見問題 FAQ

延伸閱讀

• 寫程式的 Prompt 技巧
• 用 AI 自動化文件
• Claude 怎麼用？
• 用 AI 寫 SOP