opencode-workflow/skills/generate_openapi_spec

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