35 lines
1.0 KiB
Markdown
35 lines
1.0 KiB
Markdown
# 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` 前
|
||
- **Request 驗證**：欄位可加 `validate:"required,email"` 等 tag；`make gen-api` 後 handler 會自動 `ValidateAll`（見 `generate/goctl/api/handler.tpl`）
|
||
|
||
## 與 runtime 對齊
|
||
|
||
Handler 使用 `response.Write` 輸出：
|
||
|
||
```json
|
||
{ "code": 0, "message": "SUCCESS", "data": { ... } }
|
||
```
|
||
|
||
失敗時含 `error.biz_code` 等欄位，與 `common.api` 定義一致。
|