類別 3：程式設計與技術 4 / 6
中階 Guide 16 Coding API Documentation

API 文件

用 Claude 生成全面的 API 文件 — 端點、參數、範例和錯誤處理指南。

2026年3月25日 10 min read

你將學到什麼

  • 如何提示 Claude 從程式碼或描述生成完整、結構化的 API 文件
  • 生成 OpenAPI/Swagger 規格、README 端點章節和開發者指南的技巧
  • 如何使用 Claude 保持文件的一致性，並在 API 演進時更新它

使用情境

文件是幾乎每個團隊都落後的 API 開發部分。程式碼出貨；文件滯後。新端點被添加而沒有記錄。參數改變但文件沒有。錯誤代碼激增而沒有解釋。最終，你的 API 消費者——無論是內部還是外部——都在透過試錯反向工程你的 API，而不是參考本應存在的文件。

Claude 大幅降低了撰寫 API 文件的摩擦，因為它理解程式碼背後的意圖，可以將它翻譯成結構化的、人類可讀的散文。你貼上一個路由處理器、一個控制器，或甚至只是對端點功能的描述，Claude 產出涵蓋端點目的、所有帶有類型和描述的參數、請求和回應範例，以及呼叫者應處理的錯誤情況的文件。

這對比撰寫文件的速度更快地構建 API 的團隊、需要快速了解現有端點的入門新開發者，以及需要為 Swagger UI、Postman 集合或 SDK 生成等工具產出 OpenAPI 規格的團隊特別有價值。

逐步指南

第一步：決定你的文件格式

API 文件有幾種格式，目的各不同：

  • OpenAPI 3.x YAML/JSON — 工具的機器可讀規格（Swagger UI、程式碼生成、Postman 匯入）
  • Markdown 端點參考 — README 或文件網站的人類可讀文件
  • 行內程式碼注釋 — JSDoc、Python 文件字符串、Go doc 注釋，用於 IDE 整合
  • 開發者指南散文 — 解釋身份驗證、分頁、限速的敘事性文件

告訴 Claude 你需要哪種格式。每種都需要不同的結構和細節。

第二步：提供原始素材

給 Claude 以下起點之一：

選項 A — 貼上路由處理器或控制器程式碼： 這是最可靠的方法。Claude 可以閱讀實際的實作並記錄它所做的事情，包括推斷哪些欄位是可選的等行為。

選項 B — 用自然語言描述端點： 如果你還沒有程式碼（或它用 Claude 難以處理的語言），描述端點：方法、路徑、身份驗證需求、每個參數的作用、成功是什麼樣子，以及可能出現的錯誤。

選項 C — 貼上現有的不完整文件並請求擴展： 「以下是一個部分端點描述。擴展它使其完整——添加缺少的參數，填入錯誤表，並添加請求/回應範例。」

第三步：指定你的背景中「完整」意味著什麼

不同的受眾需要不同程度的細節。告訴 Claude：

  • 誰會閱讀這個？（外部開發者、內部工程師、初級開發者）
  • 它是否需要 curl 範例？JavaScript fetch？Python requests？
  • 錯誤代碼是否應該記錄為表格？
  • 它是否需要身份驗證說明？

範例：「這是給外部開發者的公開面向文件。包括：端點描述、所有帶有類型和是否必填的路徑/查詢/主體參數、curl 範例、JSON 回應範例，以及所有可能的 HTTP 錯誤代碼及解釋的表格。」

第四步：生成 OpenAPI 規格

對於機器可讀的規格，直接問 Claude：

「為這個端點生成 YAML 格式的 OpenAPI 3.0 規格。」

提供路由處理器，Claude 將產出一個帶有正確路徑、operationId、參數、requestBody schema 和回應 schema 的結構良好的規格。然後你可以將這個貼入 Swagger Editor 進行驗證，或放入你現有的規格文件中。

第五步：隨著 API 變化維護文件

當端點改變時，同時貼上更新的程式碼和舊文件：

「以下是更新後的路由處理器和現有文件。更新文件以反映變化——新參數 sort_by，limit 的預設值從 20 改為 50，以及新的 422 錯誤情況。」

這個增量更新工作流程保持文件同步，不需要從頭重寫。

提示範本

請為以下端點生成 API 文件。

格式：[OpenAPI 3.0 YAML / Markdown 參考 / JSDoc 注釋 / 等]
受眾：[內部工程師 / 外部開發者 / 等]

端點詳情：
[貼上路由處理器程式碼，或描述以下內容：]
- 方法：[GET / POST / PUT / DELETE / 等]
- 路徑：[例如，/api/v1/users/{id}]
- 身份驗證：[Bearer token / API 金鑰 / 無]
- 描述：[這個端點做什麼]
- 路徑參數：[帶類型的清單]
- 查詢參數：[帶類型、是否必填、預設值的清單]
- 請求主體：[JSON schema 或欄位描述]
- 成功回應：[狀態碼、主體結構]
- 錯誤回應：[狀態碼以及何時發生]

包括：
- [ ] 帶類型和是否必填/可選狀態的參數描述
- [ ] curl 範例請求
- [ ] JSON 回應範例
- [ ] 錯誤代碼表

技巧與最佳實踐

  1. 包含真實的請求和回應範例，而不只是 schema — 開發者從具體範例中學習的速度比從抽象類型描述更快。始終請 Claude 在 schema 旁邊包含一個真實看起來的範例。「使用看起來真實的範例數據，而不是 string 或 1234 這樣的佔位符值。」

  2. 請 Claude 標記程式碼中的模糊之處 — 從程式碼生成文件時，添加：「如果實作中有任何不清楚或你不得不推斷而不是直接讀取的地方，請標記出來讓我驗證。」 這捕捉 Claude 不得不猜測預期行為的情況。

  3. 徹底記錄錯誤情況 — 大多數 API 文件過度記錄成功路徑而記錄錯誤不足。明確請求：「對於每個錯誤情況，描述：HTTP 狀態碼、錯誤回應主體結構、什麼觸發了這個錯誤，以及呼叫者應該對此做什麼。」

  4. 使用 Claude 一次撰寫身份驗證部分，然後重複使用 — 身份驗證在所有端點上都是相同的。請 Claude 一次徹底撰寫身份驗證部分，然後告訴它引用該部分而不是為每個端點重複它。

  5. 連同文件一起生成 Postman 集合 — 生成 OpenAPI YAML 後，問：「同時為這個端點生成一個帶有相同請求範例的 Postman 集合 JSON。」 這給開發者提供了可以立即匯入和測試的東西，而不只是閱讀。

動手試試

在你的程式碼庫中找一個沒有文件或文件稀少的 API 端點。用這個提示將路由處理器貼入 Claude：

「為這個端點生成一個完整的 Markdown API 參考。包括：一句話描述、參數表格（名稱、類型、是否必填、描述）、帶有看起來真實數據的 curl 範例、成功回應範例，以及帶有解釋的錯誤代碼表格。」

將結果添加到你的項目 README 或文件資料夾，看看新團隊成員理解和使用那個端點的速度有多快。