ROOST 專案 API 規格實務

本文件說明 ROOST 專案採用 API 規格時的最低要求。

API 文件標準

項目	說明／備註	優先順序
規格格式	具有 HTTP/REST API 的 ROOST 專案使用 OpenAPI Specification（OAS）。使用 gRPC、GraphQL 或事件驅動 API 的專案，應採用各自的原生規格格式，包括 Protocol Buffers、GraphQL SDL 與 AsyncAPI。	P0
規格位置	ROOST 慣例為將規格檔放在 repository 根目錄或 `docs/` 目錄，並從 README 連結。	P0
規格準確度	ROOST 慣例要求規格反映 API 的目前狀態。無論專案採設計優先（規格為單一真實來源）或程式碼優先（規格由程式碼產生），只要 PR 變更 API 介面，就必須同步更新規格。	P0

規格驗證

項目	說明／備註	優先順序
CI 中的 lint	在 CI 中驗證 OpenAPI 規格，例如使用 Spectral 或 Redocly CLI。	P1
破壞性變更偵測	CI 標記破壞性的 API 變更，例如移除端點或變更回應結構。當專案已有依賴 API 穩定性的下游使用者時，這會更加重要，例如 Osprey 1.0 之後。可用工具包括 oasdiff 與 openapi-diff。	P2

文件產生

項目	說明／備註	優先順序
產生文件	從規格產生人類可讀的 API 文件，例如 Redoc 或 Swagger UI。	P2
託管文件	發布產生的文件，並從 README 連結。	P2

版本管理

項目	說明／備註	優先順序
API 版本策略	如何傳達 API 版本，例如 URL 路徑或 header。	P1
淘汰通知	淘汰的端點在移除前，須先在規格中標示。	P1

冪等性

項目	說明／備註	優先順序
變更操作的冪等性	記錄哪些 `POST`、`PUT` 與 `PATCH` 端點具備冪等性。不具冪等性的 `POST` 端點應支援冪等鍵，讓用戶端能安全重試。	P1

非 HTTP API

項目	說明／備註	優先順序
函式庫／SDK 文件	對外提供函式庫或 SDK 的專案，應記錄其公開 API 介面，例如 Go 文件註解或 TypeDoc。	P1
CLI 文件	具有 CLI 的專案應記錄指令、旗標與使用方式。	P1