37 lines
1.2 KiB
Markdown
37 lines
1.2 KiB
Markdown
# API 定義（goctl + go-doc 共用）
|
||
|
||
## 檔案
|
||
|
||
| 檔案 | 用途 |
|
||
|------|------|
|
||
| `gateway.api` | 入口：`info()` + `import` |
|
||
| `common.api` | 共用文件型別（`APIErrorStatus`、`ErrorDetail`） |
|
||
| `auth.api` | Auth 路由（scope 28） |
|
||
| `member.api` | Member 路由（scope 29） |
|
||
| `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` 前
|
||
- **Request 驗證**：欄位可加 `validate:"required,email"` 等 tag；`make gen-api` 後 handler 會自動 `ValidateAll`（見 `generate/goctl/api/handler.tpl`）
|
||
|
||
## 與 runtime 對齊
|
||
|
||
Handler 使用 `response.Write` 輸出：
|
||
|
||
```json
|
||
{ "code": 102000, "message": "SUCCESS", "data": { ... } }
|
||
```
|
||
|
||
失敗時含 `error.biz_code` / `error.scope` 等欄位。Handler parse 錯誤為 Facade scope（`10101000`）；各模組 logic/usecase 使用對應 scope（Auth=28、Member=29）。
|