# 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` 前

## 與 runtime 對齊

Handler 使用 `response.Write` 輸出：

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

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