137 lines
9.2 KiB
Markdown
137 lines
9.2 KiB
Markdown
---
|
||
name: xtrader-api-docs
|
||
description: Interprets the XTrader API from the Swagger 2.0 spec at https://api.xtrader.vip/swagger/doc.json and helps implement endpoints, TypeScript types, and request helpers. Use when implementing or understanding XTrader API endpoints, adding new API calls, or when the user refers to the API docs or Swagger.
|
||
---
|
||
|
||
# XTrader API 接口文档解读
|
||
|
||
规范来源：[OpenAPI 规范](https://api.xtrader.vip/swagger/doc.json)（Swagger 2.0）。Swagger UI：<https://api.xtrader.vip/swagger/index.html>。
|
||
|
||
## 规范地址与格式
|
||
|
||
- **规范 URL**：`https://api.xtrader.vip/swagger/doc.json`
|
||
- **格式**：Swagger 2.0；接口在 `paths` 下，类型在 `definitions` 下，引用为 `#/definitions/xxx`（如 `response.Response`、`system.SysUser`）。
|
||
- **使用方式**：用 `mcp_web_fetch` 或项目内请求获取 doc.json；解析 `paths` 与 `definitions` 编写 TS 类型与请求。鉴权：请求头 `x-token`（见 `securityDefinitions.ApiKeyAuth`）。
|
||
|
||
## Swagger UI 与 doc.json 的对应关系（如何定位 Example Value / Model）
|
||
|
||
Swagger UI 页面（如 [PmEvent findPmEvent](https://api.xtrader.vip/swagger/index.html#/PmEvent/get_PmEvent_findPmEvent)）的数据来源就是 **doc.json**。页面上的「Parameters」「Responses」里的 **Example Value** 和 **Model** 都对应 doc.json 里的同一套 schema。
|
||
|
||
### 对应关系一览
|
||
|
||
| Swagger UI 上看到的 | 在 doc.json 中的位置 |
|
||
|---------------------|----------------------|
|
||
| 某个接口（如「用id查询Event Management」） | `paths["/PmEvent/findPmEvent"].get`（或对应 path + method） |
|
||
| Parameters → Body / Query | `paths["/PmEvent/findPmEvent"].get.parameters`，或 body 的 `schema`（常为 `$ref`） |
|
||
| **Responses → 200 → Model** | `paths["/PmEvent/findPmEvent"].get.responses["200"].schema`，且需把其中的 `$ref` 解析到 `definitions` |
|
||
| **Responses → 200 → Example Value** | 由同一 `responses["200"].schema` 生成（或 schema 里的 `example`）；结构同 Model |
|
||
| Model 里展开的 `data`、`user` 等对象 | `definitions` 里对应的 schema，如 `definitions["polymarket.PmEvent"]`、`definitions["system.SysUser"]` |
|
||
|
||
### 如何快速定位「响应」的 Model / 数据结构
|
||
|
||
1. **确定 path 和 method**
|
||
例如 findPmEvent：path = `/PmEvent/findPmEvent`，method = `get`。
|
||
|
||
2. **取 200 的 schema**
|
||
```text
|
||
doc.json → paths["/PmEvent/findPmEvent"].get.responses["200"].schema
|
||
```
|
||
这就是页面上 200 的 **Model** 的完整定义（可能含 `allOf`、`$ref`）。
|
||
|
||
3. **解析 allOf + $ref**
|
||
- 若 schema 为 `allOf: [ { $ref: "#/definitions/response.Response" }, { type: "object", properties: { data: { $ref: "..." }, msg } } ]`，则合并后得到根结构：`code`、`data`、`msg`。
|
||
- 对 `data` 的 `$ref`（如 `#/definitions/polymarket.PmEvent`），到 **definitions** 里找：
|
||
`definitions["polymarket.PmEvent"]`（或 `definitions["response.LoginResponse"]` 等）。
|
||
- definitions 的 key 在 JSON 里是字符串，如 `"polymarket.PmEvent"`（带引号），对应 Swagger 里 `#/definitions/polymarket.PmEvent`。
|
||
|
||
4. **Example Value**
|
||
与 Model 共用同一份 `responses["200"].schema`；Example Value 是 Swagger UI 按该 schema 生成的示例，或 schema 内 `example` 字段。所以**看响应结构时以 Model 为准**，在 doc.json 里就是上述 `responses["200"].schema` 及其引用的 `definitions`。
|
||
|
||
## 接口集成规范（必须按顺序执行）
|
||
|
||
接入任意 XTrader 接口时，**必须**按以下顺序执行，不得跳过或调换。
|
||
|
||
### 第一步：列出请求参数与响应参数
|
||
|
||
在写代码前，先从 doc.json 中整理并列出：
|
||
|
||
1. **请求参数**
|
||
- **Query**：`paths["<path>"]["<method>"].parameters` 中 `in: "query"` 的项（name、type、required、description）。
|
||
- **Body**：若存在 `in: "body"`，写出其 `schema` 对应的 `$ref` 或内联结构（来自 `definitions`）。
|
||
- **鉴权**：该接口是否带 `security: [ { ApiKeyAuth: [] } ]`，若是则需在请求头加 `x-token`。
|
||
|
||
2. **响应参数**
|
||
- 取 `paths["<path>"]["<method>"].responses["200"].schema`。
|
||
- 若有 `allOf`，合并得到根结构（通常为 `code`、`data`、`msg`）。
|
||
- 对 `data` 及其他嵌套对象的 `$ref`，到 `definitions` 中查完整结构并列出字段（名称、类型、说明）。
|
||
|
||
输出形式可为表格或结构化列表，便于第二步写类型。
|
||
|
||
### 第二步：根据响应数据创建 Model 类
|
||
|
||
- 在 `src/api/` 下相应模块（如 `event.ts`、`market.ts`）中，**根据第一步整理出的响应结构**定义 TypeScript 类型/接口：
|
||
- 根响应：如 `XxxResponse { code: number; data: XxxData; msg: string }`。
|
||
- `data` 及嵌套对象：对应 doc.json 的 `definitions`，写出完整 Model（如 `PmEvent`、`PmMarket`），避免只写 `any` 或过度使用 `[key: string]: unknown`（仅在确有扩展字段时使用）。
|
||
- 命名与项目一致：`PageResult<T>`、`XxxResponse`、`XxxParams` 等；与 `event.ts` 风格保持一致。
|
||
|
||
### 第三步：将接口集成到页面
|
||
|
||
- 在对应 API 模块中实现请求函数：使用 `get`/`post`（`src/api/request.ts`），路径、query/body 与第一步一致，返回类型使用第二步定义的 Response 类型。
|
||
- 在页面（Vue 组件）中：调用该请求函数，将返回的 `data` 绑定到组件的状态或 UI；处理 loading、错误与空数据；若为鉴权接口，确保调用时传入带 `x-token` 的 config（或使用已注入 token 的 request 封装）。
|
||
|
||
---
|
||
|
||
## 解读规范并落地的步骤
|
||
|
||
1. **Base URL**：规范中 `host` + `basePath`（可为空）；本项目已用 `src/api/request.ts` 的 `BASE_URL`（默认 `https://api.xtrader.vip`），实现时用相对 path 即可。
|
||
|
||
2. **路径与方法**：遍历 `paths`，每个 path + method 对应一个接口；path 以 `/` 开头。需鉴权接口在请求中加 `config.headers['x-token']`。
|
||
|
||
3. **请求参数**：Query 对应 `parameters` 中 `in: 'query'`；Body 对应 `in: 'body'` 的 `schema`（常为 `$ref` 到 `definitions`）。Swagger 2.0 中 body 参数名为 `data` 时，实际请求体即该 schema 的 JSON。
|
||
|
||
4. **响应类型**：看 `responses['200'].schema`；若为 `allOf`，合并 `response.Response` 与扩展中的 `data`、`msg` 等。`$ref` 到 `#/definitions/XXX` 时，在 `definitions` 中查对应结构并转为 TS 接口。统一响应包装为 `{ code, data, msg }`。
|
||
|
||
5. **与项目风格一致**：新接口放在 `src/api/` 下；导出请求/响应类型及调用 `get`/`post` 的函数；类型命名与 `event.ts` 一致（如 `PageResult<T>`、`XxxResponse`）。
|
||
|
||
## 已知接口（来自 doc.json）
|
||
|
||
### 钱包登录 `POST /base/walletLogin`
|
||
|
||
- **请求体**（`definitions.request.WalletLogin`）：`{ message: string, nonce: string, signature: string, walletAddress: string }`。
|
||
- **响应 200**：`{ code, data, msg }`；`data` 为 `response.LoginResponse`。
|
||
- **response.LoginResponse**：`{ expiresAt: number, token: string, user: system.SysUser }`。
|
||
- **system.SysUser**（`data.user`）：含 **ID**（integer，主键）、userName、nickName、headerImg、uuid、authorityId、authority、createdAt、updatedAt、email、phone、enable、walletAddress 等。**返回结果中包含用户 id，对应字段为 `user.ID`**（JSON 中可能为 `ID` 或 `id`，与后端序列化一致即可）。
|
||
- **项目映射**：`src/views/Login.vue` 调该接口；`src/stores/user.ts` 的 `UserInfo` 建议包含 `id?: number | string` 并与 `data.user.ID` 对应。
|
||
|
||
### 公开事件列表 `GET /PmEvent/getPmEventPublic`
|
||
|
||
- **Query**：page、pageSize、keyword、createdAtRange（array）、tokenid（可选，来自 market.clobTokenIds 的值，可传单个或数组）。
|
||
- **响应 200**：`data` 为 `response.PageResult`（list、page、pageSize、total）；list 项为 `polymarket.PmEvent`，内含 markets、series、tags 等，markets[].outcomePrices 为价格数组，首项对应 Yes 概率；markets[].clobTokenIds 与 outcomes/outcomePrices 顺序一致。
|
||
|
||
### 订单类型与交易方向（用于交易接口，`src/api/constants.ts`）
|
||
|
||
- **OrderType**：GTC=0（一直有效直到取消）、GTD=1（指定时间内有效）、FOK=2（全部成交或取消）、FAK=3（立即成交剩余取消）、Market=4（市价单）。
|
||
- **Side**：Buy=1、Sell=2。
|
||
|
||
### 通用响应与鉴权
|
||
|
||
- **response.Response**：`{ code: number, data: any, msg: string }`。
|
||
- **response.PageResult**：`{ list, page, pageSize, total }`。
|
||
- 需鉴权接口在文档中带 `security: [ { ApiKeyAuth: [] } ]`，请求时加 header `x-token`。
|
||
|
||
## 简要检查清单
|
||
|
||
- [ ] **按规范顺序**：已先列出请求参数与响应参数，再建 Model，最后集成到页面
|
||
- [ ] 规范 URL 使用 `https://api.xtrader.vip/swagger/doc.json`，或本地缓存与之一致
|
||
- [ ] 请求 path、method、query/body 与 `paths` 一致
|
||
- [ ] 响应类型（Model）覆盖 `code`/`data`/`msg` 及 `definitions` 中业务字段
|
||
- [ ] 鉴权接口使用 `x-token` header
|
||
- [ ] 新代码风格与 `src/api/request.ts`、`src/api/event.ts` 一致
|
||
|
||
## 参考
|
||
|
||
- 规范：<https://api.xtrader.vip/swagger/doc.json>
|
||
- Swagger UI：<https://api.xtrader.vip/swagger/index.html>
|
||
- 项目请求封装：`src/api/request.ts`
|
||
- 现有接口与类型：`src/api/event.ts`
|