新增接口及接口文档

2026-04-27 00:32:09 +08:00
parent 7a7e28684c
commit ee1707c17f
10 changed files with 830 additions and 2 deletions
@@ -0,0 +1,83 @@
+# 股票历史 K 线接口文档
+
+## 1. 接口说明
+
+- 接口名称：股票历史 K 线
+- 请求方式：`GET`
+- 请求路径：`/api/v1/stock/kline/:code`
+- 接口用途：获取指定股票自 `2024-09-24` 起的历史日线数据。
+
+## 2. 请求参数
+
+路径参数：
+
+| 参数名 | 类型 | 必填 | 示例 | 说明 |
+| --- | --- | --- | --- | --- |
+| `code` | `string` | 是 | `000001.SZ` | TS 股票代码 |
+
+请求示例：
+
+```http
+GET /api/v1/stock/kline/000001.SZ
+```
+
+## 3. 响应说明
+
+返回值为数组，每个元素代表一个交易日的 K 线数据。
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `ts_code` | `string` | TS 股票代码 |
+| `trade_date` | `string` | 交易日时间 |
+| `open` | `number` | 开盘价 |
+| `high` | `number` | 最高价 |
+| `low` | `number` | 最低价 |
+| `close` | `number` | 收盘价 |
+| `pct_chg` | `number` | 涨跌幅 |
+
+## 4. 响应示例
+
+```json
+[
+  {
+    "ts_code": "000001.SZ",
+    "trade_date": "2026-04-21T00:00:00+08:00",
+    "open": 10.01,
+    "high": 10.55,
+    "low": 9.98,
+    "close": 10.43,
+    "pct_chg": 3.24
+  }
+]
+```
+
+## 5. 业务规则
+
+- 查询起始日期固定为 `2024-09-24`。
+- 返回结果按 `trade_date` 升序排序。
+
+## 6. 空数据说明
+
+若指定股票无数据，返回空数组：
+
+```json
+[]
+```
+
+## 7. 错误响应
+
+当路径参数为空时：
+
+```json
+{
+  "error": "股票代码不能为空"
+}
+```
+
+当服务端内部异常时：
+
+```json
+{
+  "error": "具体错误信息"
+}
+```