151 lines
10 KiB
Markdown
151 lines
10 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>。
|
||
|
||
---
|
||
|
||
## ⚠️ 强制执行：接口接入三步流程
|
||
|
||
**接入任意 XTrader 接口时，必须严格按以下顺序执行，不得跳过、不得调换、不得合并步骤。**
|
||
|
||
| 步骤 | 动作 | 强制要求 |
|
||
|------|------|----------|
|
||
| **第一步** | 从 doc.json 整理并**在对话中输出**请求参数表、响应参数表、definitions 完整结构 | 在输出第一步结果**之前**，不得写任何业务代码；必须用 `mcp_web_fetch` 或 curl 获取 doc.json，解析 `paths` 与 `definitions` |
|
||
| **第二步** | 根据第一步整理出的结构，在 `src/api/` 中定义 TypeScript 类型 | 必须等第一步输出完成后再执行；Model 必须与 definitions 对应 |
|
||
| **第三步** | 实现请求函数并集成到页面 | 必须等第二步完成后再执行 |
|
||
|
||
**违反后果**：若跳过第一步直接写代码，会导致类型与接口文档不一致、遗漏字段或误用参数。
|
||
|
||
## 规范地址与格式
|
||
|
||
- **规范 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 接口时，**必须**按以下顺序执行，不得跳过或调换。**第一步的输出必须在对话中可见，才能进入第二步。**
|
||
|
||
### 第一步：列出请求参数与响应参数
|
||
|
||
**在写任何代码之前**，先用 `mcp_web_fetch` 或 curl 获取 `https://api.xtrader.vip/swagger/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`
|