此技能提供全面的指導，幫助開發者遵循產業最佳實務來設計 RESTful 與 GraphQL API。它能協助建立結構完善、版本控制正確且有完整文件的 API。
下載技能 ZIP
在 Claude 中上傳
前往 設定 → 功能 → 技能 → 上傳技能
開啟並開始使用
測試它
正在使用「api-design」。 設計部落格文章與留言的 REST API
預期結果:
端點：GET/POST /api/v1/posts、GET/PUT/DELETE /api/v1/posts/{id}、GET/POST /api/v1/posts/{id}/comments，回應代碼：200、201、204、400、401、403、404
正在使用「api-design」。 建立使用者管理的 OpenAPI 規格
預期結果:
OpenAPI 3.0 搭配 /users 端點，GET（分頁列出使用者）、POST（建立使用者）、JWT Bearer 驗證、200/201 回應搭配 User 結構定義
安全審計
安全All 76 static findings are false positives. The skill is pure documentation providing API design guidance. The scanner detected backtick formatting in markdown examples, legitimate documentation URLs, and JWT authentication references - none of which constitute security risks.
偵測到的模式
品質評分
你能建構什麼
新 API 開發
在開始新 API 專案時使用，以建立正確的慣例、資源命名及端點結構
API 文件
為現有或新 API 產生 OpenAPI 規格及文件，分享給前端團隊及外部消費者
API 審查與重構
根據最佳實務審查現有 API 設計，找出命名、版本控制及結構方面的改進之處
試試這些提示
為 [resource name] 資源設計 REST API。包含端點定義、HTTP 方法、回應代碼及請求/回應格式。
為具有這些端點的 API 產生 OpenAPI 3.0 規格：[list endpoints]。包含請求/回應結構定義、參數及驗證。
為 [use case] 設計 GraphQL 結構定義。包含類型定義、查詢、變更及適當的解析器。
最佳實務
- 使用一致的資源命名，使用名詞而非動詞，並採用複數形式
- 從一開始就使用 URL 路徑版本控制來對 API 進行版本管理（例如：/api/v1/）
- 實作正確的錯誤處理，使用一致的錯誤回應格式，包含錯誤碼及詳細資訊
避免
- 在端點名稱中使用動詞（例如：/getUsers 而非 /users）
- 不對 API 進行版本控制，導致需要變更時影響用戶端
- 在不同端點回傳不同的錯誤格式