一份合格的 API 文件，要讓沒參與開發的工程師只看文件就能完成呼叫，至少寫清楚七件事：有哪些端點與 HTTP 方法、用什麼方式驗證身分、每個參數的位置型別與是否必填、可能回傳的錯誤代碼與錯誤格式、可以直接執行的請求與回應範例、測試環境，以及版本規則與舊版棄用的通知方式。系統外包驗收時，不要只看文件頁數，而是請另一位工程師照文件從頭呼叫一次，逐項對照實際回應；廠商交付 OpenAPI 格式的檔案時，也要確認規格版本與 API 自己的版本都標示清楚。
API 文件的組成：概覽、教學、參考與變更紀錄
API 的基本概念見API 是什麼。完整的文件通常分成幾個部分，驗收時逐項確認：
- 概覽：用途、測試與正式環境的伺服器網址、技術聯絡窗口。
- 入門教學：從申請帳號或金鑰到完成初次呼叫的步驟。
- 參考文件：每個端點的說明。
- 錯誤代碼表：所有自訂錯誤代碼的意思與處理方式。
- 變更紀錄：每次改版的日期、內容與影響範圍。
參考文件常用 OpenAPI 規格撰寫。依 spec.openapis.org，OpenAPI 規格定義了描述 HTTP API 的標準介面，與程式語言無關，文件可用 JSON 或 YAML 表示。根層的 openapi 欄位必填，寫採用的規格版本號；info 也必填，其中 title 與 version 必填，這個 version 是文件自己的版本，和規格版本不同；paths、components、webhooks 至少要有一個。
端點與參數的檢查項目
每個端點都要能回答下面的問題，HTTP 方法與狀態碼的基本觀念見RESTful API 是什麼：
- 路徑與方法：網址路徑、HTTP 方法，以及這個操作對應的業務動作。
- 參數位置：每個參數放在哪裡。spec.openapis.org 的 v3.2.1 列出 query、querystring、header、path、cookie；v3.1.2 沒有 querystring，選工具時要確認支援文件宣告的版本。
- 型別與限制：資料型別、格式、長度、允許的值與預設值，必填或選填。
- 請求本文：欄位結構、巢狀物件與陣列的寫法，並附範例。
- 回應欄位：每個欄位的意思、可能為空值的情況、時間格式與時區、金額的單位。
- 清單類端點：分頁、排序與篩選的參數與上限。
欄位說明只有名稱沒有意義，或只寫「字串」沒有長度與格式，串接方就得靠猜，這一項就不算通過。
驗證方式與權限怎麼寫
- 驗證機制：使用 API 金鑰、OAuth 權杖或其他方式，請求要放在哪個標頭或參數。OpenAPI 的 security 欄位可以宣告整份 API 能使用的安全機制，文件與實際設定要一致。
- 取得與更新：金鑰或權杖怎麼申請、有效期限多久、過期後怎麼更新。
- 權限範圍：每個端點需要什麼權限，不同角色能存取哪些資料。
- 環境區隔：測試與正式環境的帳號、金鑰分開，測試資料不會進入正式環境。
- 範例中的金鑰：用明顯的假值代替，不放真實的金鑰或權杖。
金鑰與權杖的差別與保管方式，可參考API Key 和 Token 的差別。
錯誤代碼與錯誤回應格式
文件要列出每個端點可能回傳的 HTTP 狀態碼，並和 MDN 的定義一致。常見而容易混淆的幾個：
- 400：伺服器認為是用戶端的錯誤而不處理請求，例如格式錯誤。
- 401：請求缺少目標資源的有效驗證憑證。
- 403：伺服器理解請求但拒絕處理，重新驗證也沒有差別。
- 429：一段時間內送出過多請求，也就是頻率限制；回應可以附 Retry-After 標頭，說明要等多久再試。
錯誤本文的格式也要固定。RFC 9457 定義了機器可讀的錯誤細節格式，媒體類型為 application/problem+json，標準成員包括 type、title、status、detail 與 instance，可以作為設計參考。另外附一張自訂錯誤代碼表，欄位包括代碼、意思、可否重試與建議處理方式。
範例與測試環境的檢查
- 每個端點至少有一組成功與一組失敗的請求與回應範例。
- 範例要完整到可以直接執行：網址、方法、標頭與請求本文都寫出來，不省略必要欄位。
- 範例的回應要和實際回應一致，欄位名稱與型別不能只存在文件裡。
- 測試環境的網址、測試帳號與測試資料的重設方式，以及測試環境和正式環境的差異。
- 有事件通知時，寫出通知的格式、重送規則與來源驗證方式；OpenAPI 的 webhooks 欄位，用來描述串接方可能收到、可以選擇實作接收的 webhook。
版本與棄用政策要寫清楚的事
文件要說明版本標示在哪裡，例如網址路徑或標頭，以及哪些修改算是會影響既有串接的變更。棄用舊功能時可以這樣處理：
- 在文件中標示。OpenAPI 的操作與參數都有 deprecated 欄位，標示後串接方應避免使用該操作、逐步淘汰該參數。
- 在回應中提示。RFC 9745 定義了 Deprecation 回應標頭，用來告知資源已經或將會被棄用；棄用本身不改變資源的行為。預計停止回應時，可以搭配 Sunset 標頭，時間不得早於 Deprecation 標頭所示。
- 事先通知。通知方式、提前多久通知、舊版保留多久，寫進合約或服務條款。
外包驗收時怎麼實際測試文件
- 對照需求規格書，確認每個需要串接的功能都有對應端點。
- 取得 OpenAPI 原始檔，用支援該版本的工具檢查格式，確認 openapi 與 info 中的 version 欄位都有填寫。
- 請沒參與開發的工程師，只看文件從申請金鑰到完成一次呼叫，記下卡住的地方。
- 逐一執行文件中的範例，比對實際回應的欄位、型別與狀態碼。
- 刻意製造錯誤情境：缺少必填參數、權杖過期、權限不足、短時間大量呼叫，確認回應和文件一致。
- 確認文件跟著程式更新的責任、交付格式與權利歸屬已寫進合約。
缺漏的優先順序與後續處理
檢查完把缺漏分成三級。會讓呼叫失敗或造成資安風險的列為上線前必修，例如驗證方式寫錯、必填欄位漏列、錯誤代碼和實際回應不符；會造成誤解但不致失敗的，例如欄位說明模糊、範例不完整，在驗收前補齊；教學與排版的改善可以排入維護。每一項寫下發現的情境、預期與實際結果，廠商修正後再用同一個情境複驗，並記入變更紀錄。
常見問題
API 文件一定要用 OpenAPI 格式嗎？
不一定，但建議要求。OpenAPI 是描述 HTTP API 的標準格式，與程式語言無關，可用 JSON 或 YAML 保存，方便交接與檢查。若廠商用其他格式，至少要求內容涵蓋同樣的項目，並能匯出可保存的檔案。
API 文件應該由誰撰寫？
通常由開發廠商的工程師撰寫，因為實作的人才知道實際行為；委託方負責確認文件涵蓋需求規格，並安排沒參與開發的人試用。合約要寫明文件屬於交付項目與改版時的更新責任。
API 文件可以公開嗎？
依用途而定。給合作夥伴或開發者使用的 API 可以公開文件，內部系統的文件則建議只給有需要的人。公開前要移除測試帳號、內部網址與真實資料，金鑰與權杖一律不寫進文件。
系統上線後文件沒有更新怎麼辦？
先比對變更紀錄與實際回應，列出不一致的地方請廠商補正。之後把文件更新列入每次改版的完成條件，程式改了文件沒改就不算完成，驗收時抽測幾個端點確認一致。
沒有測試環境可以驗收 API 嗎？
可以做部分驗收，但風險較高，因為錯誤情境與資料寫入的測試可能影響正式資料。建議在合約中要求廠商提供測試環境與測試帳號，至少能重設測試資料，讓驗收可以重複進行。
本文由京采數位科技整理。我們自 2005 年起提供官網設計、系統開發與 Google SEO 服務，實際案例可見成果與案例。
想直接討論你自己的網站狀況，或需要一份初步的搜尋機會評估？
相關主題
下一步
正準備外包系統或驗收廠商交付的 API，可以先把這份清單放進需求規格書與驗收條件。京采承接系統開發時，可以在規格階段一併定義 API 文件的格式與交付內容，上線前用測試環境逐項驗證範例與錯誤情境；相關規劃可參考網頁設計服務，或與我們聯繫討論你的串接需求。
