template-monorepo/generate/api/README.md

API 定義（goctl + go-doc 共用）

檔案

檔案	用途
gateway.api	入口：info() + import
common.api	共用文件型別（APIErrorStatus、ErrorDetail）
normal.api	路由與業務 data 型別

指令

make gen-api   # 生成 handler / logic / types
make gen-doc   # 生成 docs/openapi/gateway.yaml（OpenAPI 3.0）

註解約定

• Logic returns：只寫業務 data（如 PingData）
• 文件 @respdoc：寫實際 HTTP JSON（如 PingOKStatus、APIErrorStatus）
• @doc：單一 API 的 summary / description
• 多狀態碼用 /* @respdoc-200 ... */ 區塊，放在 @handler 前
• Request 驗證：欄位可加 validate:"required,email" 等 tag；make gen-api 後 handler 會自動 ValidateAll（見 generate/goctl/api/handler.tpl）

與 runtime 對齊

Handler 使用 response.Write 輸出：

{ "code": 0, "message": "SUCCESS", "data": { ... } }

失敗時含 error.biz_code 等欄位，與 common.api 定義一致。