29 lines
1.3 KiB
Markdown
29 lines
1.3 KiB
Markdown
|
# 產生 OpenAPI 規格 (Generate OpenAPI Spec) 技能指南
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
`generate_openapi_spec` 是可交付技能，用來產生 OpenAPI 或 gRPC API 合約定義，包含端點、請求/回應結構、錯誤碼、Idempotency、分頁與過濾。供 `design-architecture` 在產生 API Contract 章節時參考。
|
|||
|
|
|
|||
|
|
## 核心原則
|
|||
|
|
API 合約定義必須具體到足以供實作使用。每個端點必須服務至少一個 PRD 功能需求。
|
|||
|
|
|
|||
|
|
## REST API 必備元素
|
|||
|
|
- **端點定義**：方法、路徑、請求結構、回應結構
|
|||
|
|
- **錯誤碼**：一致的錯誤碼與錯誤回應格式
|
|||
|
|
- **Idempotency**：哪些端點需要、機制是什麼
|
|||
|
|
- **分頁**：列表端點的分頁機制與回應格式
|
|||
|
|
- **過濾**：支援哪些過濾欄位與運算子
|
|||
|
|
|
|||
|
|
## gRPC API 必備元素
|
|||
|
|
- **Service 定義**：Package、Service name、Methods
|
|||
|
|
- **Message 定義**：Request / Response 訊息結構
|
|||
|
|
- **錯誤碼**：gRPC status codes
|
|||
|
|
|
|||
|
|
## 防範佔位符規則
|
|||
|
|
範例僅供說明用途。不要重複使用範例中的佔位符端點、欄位名稱、回應結構或錯誤碼。
|
|||
|
|
|
|||
|
|
## 知識合約職責
|
|||
|
|
- 與 `api-contract-design` 知識合約搭配使用：前者提供理論原則，後者提供格式
|
|||
|
|
|
|||
|
|
## 不應做的事
|
|||
|
|
- 不替非 PRD 要求的端點定義結構
|
|||
|
|
- 不產生獨立 OpenAPI YAML 或 gRPC proto 檔案（所有內容必須嵌入 `docs/architecture/{feature}.md`）
|