初始化
This commit is contained in:
268
docs/open-api-doc.md
Normal file
268
docs/open-api-doc.md
Normal file
@@ -0,0 +1,268 @@
|
||||
# Mokee Gateway 对外开放 API 文档
|
||||
|
||||
**网关地址**: `https://gw.server.zgitm.com`
|
||||
**版本**: v1
|
||||
**更新时间**: 2026-06-13
|
||||
|
||||
---
|
||||
|
||||
## 1. 概述
|
||||
|
||||
对外开放 API 用于外部业务系统接入 Mokee 网关平台，支持获取一次性 Token、校验 Token、标记 Token 已消费、发送邮件等功能。
|
||||
|
||||
> 📦 **文件上传/下载** 已迁移至独立的文件对象存储服务 `file.wg.zgitm.com`，详见 [文件对象存储服务 API 文档](#10-文件对象存储服务)。
|
||||
|
||||
> ⚠️ **编码要求**：所有请求和响应均使用 **UTF-8** 编码。
|
||||
|
||||
### 认证流程
|
||||
|
||||
```
|
||||
外部系统 ──POST /zgapi/v1/open/token──▶ 获取一次性 Token
|
||||
外部系统 ──POST /zgapi/v1/open/token/validate──▶ 校验 Token（不消费）
|
||||
外部系统 ──GET /zgapi/v1/open/token/info──▶ 查询系统信息（不消费）
|
||||
外部系统 ──POST /zgapi/v1/open/token/consume──▶ 标记 Token 已消费
|
||||
外部系统 ──POST /zgapi/v1/open/email/send──▶ 发送邮件（消费 Token）
|
||||
```
|
||||
|
||||
### Token 规则
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| 获取方式 | 传入 `systemCode` 即可获取，无需密钥 |
|
||||
| 有效期 | 获取后 **12 小时**内有效 |
|
||||
| 消费限制 | 每个 Token **只能使用一次**，调用任意接口即消费 |
|
||||
| 消费失败 | 接口调用失败（如邮件发送失败）**不消费** Token，可重试 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 获取 Token
|
||||
|
||||
传入系统编码，获取一次性 JWT Token。
|
||||
|
||||
**请求**
|
||||
|
||||
```
|
||||
POST /zgapi/v1/open/token
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|:--:|------|
|
||||
| systemCode | string | 是 | 系统编码，需在网关平台已注册且启用 |
|
||||
|
||||
**请求示例**
|
||||
|
||||
```bash
|
||||
curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"systemCode": "gateway"}'
|
||||
```
|
||||
|
||||
**响应**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": {
|
||||
"token": "eyJhbGciOiJIUzM4NCJ9.eyJzdWIiOi...",
|
||||
"expiresIn": 43200,
|
||||
"systemName": "网关管理平台",
|
||||
"usageNote": "此 Token 只能消费一次，消费后立即失效"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| code | int | 200=成功 |
|
||||
| data.token | string | JWT Token，后续请求放入 Authorization 头 |
|
||||
| data.expiresIn | int | 有效时间（秒），43200 = 12小时 |
|
||||
| data.systemName | string | 系统名称 |
|
||||
| data.usageNote | string | 使用提示 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 校验 Token（不消费）
|
||||
|
||||
检查 Token 是否有效。**不会消费 Token**。
|
||||
|
||||
```
|
||||
POST /zgapi/v1/open/token/validate
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|:--:|------|
|
||||
| token | string | 是 | 需要校验的 JWT Token |
|
||||
|
||||
```bash
|
||||
curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token/validate" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"token": "eyJhbGciOiJIUzM4NCJ9..."}'
|
||||
```
|
||||
|
||||
**成功响应**
|
||||
|
||||
```json
|
||||
{ "code": 200, "data": { "valid": true, "systemCode": "gateway", "msg": "Token 有效，未被消费" } }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 查询 Token 系统信息（不消费）
|
||||
|
||||
根据 Token 查询所属系统信息。**不消费 Token**，不检查已消费状态，仅从 JWT 解析。
|
||||
|
||||
```
|
||||
GET /zgapi/v1/open/token/info?token=<token>
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|:--:|------|
|
||||
| token | string | 是 | query 参数传递 JWT Token |
|
||||
|
||||
```bash
|
||||
curl "https://gw.server.zgitm.com/zgapi/v1/open/token/info?token=eyJhbGciOiJIUzM4NCJ9..."
|
||||
```
|
||||
|
||||
**成功响应**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": {
|
||||
"systemId": "30957c6264d511f18b7900e04c896f92",
|
||||
"systemCode": "gateway",
|
||||
"systemName": "网关管理平台"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| data.systemId | string | 系统唯一 ID |
|
||||
| data.systemCode | string | 系统编码 |
|
||||
| data.systemName | string | 系统名称 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 标记 Token 已消费
|
||||
|
||||
外部系统在自己的业务中消费了 Token 后，调用此接口告知网关。
|
||||
|
||||
```
|
||||
POST /zgapi/v1/open/token/consume
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|:--:|------|
|
||||
| token | string | 是 | 需要标记的 Token |
|
||||
| action | string | 是 | 消费动作，如 `发送邮件` / `上传文件` |
|
||||
|
||||
```bash
|
||||
curl -X POST "https://gw.server.zgitm.com/zgapi/v1/open/token/consume" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"token": "eyJ...", "action": "上传文件"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 发送邮件
|
||||
|
||||
使用 Token 认证后发送邮件。**调用此接口将消费当前 Token。**
|
||||
|
||||
```
|
||||
POST /zgapi/v1/open/email/send
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|:--:|------|
|
||||
| to | string | 是 | 收件人邮箱 |
|
||||
| subject | string | 是 | 邮件主题 |
|
||||
| content | string | 是 | 邮件内容 |
|
||||
| contentType | string | 否 | `html`（默认）或 `text` |
|
||||
|
||||
---
|
||||
|
||||
## 7. Java 调用示例
|
||||
|
||||
```java
|
||||
import cn.hutool.http.HttpRequest;
|
||||
|
||||
public class OpenApiDemo {
|
||||
private static final String BASE = "https://gw.server.zgitm.com";
|
||||
|
||||
public static void main(String[] args) {
|
||||
// 1. 获取 Token
|
||||
String tokenResp = HttpRequest.post(BASE + "/zgapi/v1/open/token")
|
||||
.body("{\"systemCode\":\"gateway\"}").execute().body();
|
||||
String token = JSONUtil.parseObj(tokenResp).getJSONObject("data").getStr("token");
|
||||
|
||||
// 2. 校验 Token
|
||||
String validResp = HttpRequest.post(BASE + "/zgapi/v1/open/token/validate")
|
||||
.body("{\"token\":\"" + token + "\"}").execute().body();
|
||||
System.out.println(validResp);
|
||||
|
||||
// 3. 发送邮件
|
||||
String emailResp = HttpRequest.post(BASE + "/zgapi/v1/open/email/send")
|
||||
.header("Authorization", "Bearer " + token)
|
||||
.body("{\"to\":\"user@example.com\",\"subject\":\"测试\",\"content\":\"<h1>Hello</h1>\"}")
|
||||
.execute().body();
|
||||
System.out.println(emailResp);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 文件对象存储服务
|
||||
|
||||
文件上传/下载/删除功能由独立的文件对象存储服务提供。
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| 服务地址 | `https://file.wg.zgitm.com` |
|
||||
| 认证方式 | Bearer Token（一次一密） |
|
||||
| 最大文件 | 100MB |
|
||||
| 文档 | 详见文件服务 API 文档 |
|
||||
|
||||
**快速示例**：
|
||||
|
||||
```bash
|
||||
# 获取 Token
|
||||
TOKEN=$(curl -s -X POST https://file.wg.zgitm.com/api/token \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"systemCode":"gateway"}' | jq -r '.data.token')
|
||||
|
||||
# 上传
|
||||
curl -X POST https://file.wg.zgitm.com/api/upload \
|
||||
-H "Authorization: Bearer $TOKEN" -F "file=@/path/to/file.pdf"
|
||||
|
||||
# 下载（两种方式等效）
|
||||
# 方式1: Header 传 Token
|
||||
curl -H "Authorization: Bearer $TOKEN" -o output.pdf \
|
||||
https://file.wg.zgitm.com/api/download/{fileId}
|
||||
# 方式2: URL Query 参数传 Token（浏览器直链时使用）
|
||||
curl -o output.pdf \
|
||||
"https://file.wg.zgitm.com/api/download/{fileId}?token=$TOKEN"
|
||||
|
||||
# 删除
|
||||
curl -H "Authorization: Bearer $TOKEN" \
|
||||
https://file.wg.zgitm.com/api/delete/{fileId}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 附录
|
||||
|
||||
### 错误码汇总
|
||||
|
||||
| HTTP | code | 说明 |
|
||||
|:----:|:----:|------|
|
||||
| 200 | 200 | 成功 |
|
||||
| 200 | 400 | 参数错误 |
|
||||
| 200 | 401 | 认证失败 |
|
||||
| 200 | 500 | 服务内部错误 |
|
||||
Reference in New Issue
Block a user