# 產生 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`）