文件化不是做完才補，是設計的一部分
一句話總結：好的 API 文件應該自動產生、即時更新，而不是某個工程師在 deadline 前一天趕出來的 PDF。
結論先講：用 OpenAPI 規範定義 API，工具自動產生文件和 client SDK。手寫的文件一定會過期，自動產生的才能跟 code 同步。
OpenAPI：API 的真相只有一份
OpenAPI Specification（前身叫 Swagger）是描述 RESTful API 的標準格式。你用 YAML 或 JSON 定義 API 的結構，然後工具自動幫你產生好看的互動式文件。
為什麼要用 OpenAPI 而不是手寫文件？因為手寫文件有個致命問題：它一定會跟 code 脫節。 上線一個月後，新增了三個欄位、改了一個錯誤碼，文件還是舊的。然後前端工程師拿著文件來找你，你說「喔那個已經改了」，前端工程師的眼神你自己想像。
常見的工具鏈：
- Swagger UI：把 OpenAPI spec 渲染成互動式頁面，可以直接在上面試打 API
- Redoc：比 Swagger UI 好看，適合對外的 API 文件
- swagger-jsdoc：從 JSDoc 註解自動產生 OpenAPI spec，code 即文件
- tsoa / NestJS Swagger：從 TypeScript 裝飾器自動產生，更無痛
我的建議是 code-first：先寫 code，用裝飾器或註解自動產出 spec。這樣 API 改了，文件自動跟著改。
API 測試工具
文件寫好了，接下來要能測試。幾個好用的工具：
- Postman：最廣泛使用，支援集合、環境變數、自動化測試。團隊共享 collection 很方便
- Insomnia：更輕量，介面簡潔，不想用 Postman 的可以試試
- Thunder Client：VS Code 擴充，不離開編輯器就能測 API
- curl / httpie：命令列工具，CI/CD 整合用
五個最常見的 API 設計陷阱
陷阱一：命名不一致
同一個團隊裡，A 工程師寫 /getUsers，B 工程師寫 /user-list，C 工程師寫 /fetch_orders。三種命名風格並存，前端工程師每串一個 endpoint 都要查文件。
解法很簡單但執行很難——制定 API Style Guide 並在 Code Review 嚴格把關。更好的做法是用 spectral 這類 linter 工具自動檢查 OpenAPI spec 是否符合規範。
陷阱二：JWT 存 localStorage
前一篇已經說過了，但因為太多教學文章這樣教，值得再強調一次：localStorage 在 XSS 面前毫無防禦力。 Access Token 存記憶體、Refresh Token 存 HttpOnly Cookie，沒有第三種選擇。
陷阱三：沒有速率限制
你的 API 裸奔在網路上，任何人都能無限制地打。結果？DDoS 打你、暴力破解你的登入、爬蟲抓光你的資料、API 雲端帳單炸掉。
全域速率限制是基本，敏感端點（登入、密碼重設、驗證碼發送）要更嚴格。用 API Gateway 層級的限制效率最高。
陷阱四：沒有版本管理
API 改了一個欄位名稱，所有 client 同時炸掉。
從第一天就用 /v1/ 前綴。新版本上線後，舊版本要給一個 deprecation 期。在回應 header 加 Deprecation 和 Sunset 標頭通知 client「你用的版本快下架了」。
陷阱五：錯誤格式亂七八糟
有的 endpoint 回 { message: "..." }，有的回 { error: "..." }，有的直接回純文字。前端每串一個 API 都要寫特殊的 error handling。
解法：實作全域錯誤處理 middleware，所有錯誤都經過同一個格式化層再回傳。格式統一了，前端一個 interceptor 就搞定。
HATEOAS：知道就好
HATEOAS 是 REST 的最高成熟度等級——回應裡包含相關操作的連結，讓 client 可以「探索」API。理論上很美，實務上大多數前端在編譯時就確定了 API 路徑，根本不會動態解析這些連結。
除非你在設計一個需要高度動態探索的公開 API（像 GitHub API 那種規模），不然 HATEOAS 就是「面試會問，工作不會用」的東西。
系列總結
四篇走完了 API 設計的全貌：
| 篇章 | 核心重點 |
|---|---|
| RESTful 基礎 | URL 命名、HTTP 方法語義、狀態碼、分頁、版本管理 |
| 認證機制 | JWT + Access/Refresh Token、OAuth 2.0、API Key、Rate Limiting |
| 實戰程式碼 | Express Router、JWT Middleware、Rate Limiter |
| 文件化 + 陷阱 | OpenAPI 自動產生文件、五個常見設計陷阱 |
API 設計不只是技術選擇，更是團隊協作的基礎。一致性優先、安全性不妥協、文件即契約、版本管理從第一天開始。
系列文章：
- API 設計（一）：RESTful 基礎
- API 設計（二）：認證機制
- API 設計（三）：實戰程式碼
- 你在這裡 → API 設計（四）：文件化與陷阱
延伸閱讀：
- Proto 規劃方法論（API 設計實踐章節）
- 測試策略
「API 文件就像遺囑——你不會想在需要的時候才發現它沒寫。」