2026-05-19 11:00:28 +00:00
|
|
|
|
# API 定義（goctl + go-doc 共用）
|
|
|
|
|
|
|
|
|
|
|
|
## 檔案
|
|
|
|
|
|
|
|
|
|
|
|
| 檔案 | 用途 |
|
|
|
|
|
|
|------|------|
|
|
|
|
|
|
| `gateway.api` | 入口：`info()` + `import` |
|
|
|
|
|
|
| `common.api` | 共用文件型別（`APIErrorStatus`、`ErrorDetail`） |
|
|
|
|
|
|
| `normal.api` | 路由與業務 `data` 型別 |
|
|
|
|
|
|
|
|
|
|
|
|
## 指令
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
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` 前
|
2026-05-19 12:56:32 +00:00
|
|
|
|
- **Request 驗證**：欄位可加 `validate:"required,email"` 等 tag；`make gen-api` 後 handler 會自動 `ValidateAll`（見 `generate/goctl/api/handler.tpl`）
|
2026-05-19 11:00:28 +00:00
|
|
|
|
|
|
|
|
|
|
## 與 runtime 對齊
|
|
|
|
|
|
|
|
|
|
|
|
Handler 使用 `response.Write` 輸出：
|
|
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
|
{ "code": 0, "message": "SUCCESS", "data": { ... } }
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
失敗時含 `error.biz_code` 等欄位，與 `common.api` 定義一致。
|
