WMS_MAIN/methods/openapi.json
2026-04-27 16:09:26 +08:00

161 lines
7.0 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

{
"module": "openapi",
"description": "开放 API 统一入口,独立链路,HTTP POST /openapi,记录入口校验/鉴权规则与返回格式。",
"version": "2026.04.26-openapi-04",
"updatedAt": "2026-04-26",
"http": {
"path": "/openapi",
"method": "POST"
},
"headers": [],
"endpoints": [
{
"method": "openapi.index",
"description": "开放 API 统一入口,接收 POST /openapi;完成 JSON body 解析、app_key 校验与签名校验,返回统一响应(与系统 style 的 code/message/data 保持一致)。",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [
{
"name": "method",
"type": "string",
"required": true,
"source": "query",
"description": "目标系统方法名,必填(例如 order.list)"
},
{
"name": "v",
"type": "string",
"required": true,
"source": "query",
"description": "API 版本号"
},
{
"name": "timestamp",
"type": "number",
"required": true,
"source": "query",
"description": "时间戳(数字)"
},
{
"name": "app_key",
"type": "string",
"required": true,
"source": "query",
"description": "开放平台分配的 app_key;兼容别名 appkey 与 self_app_key(任一存在即可)"
},
{
"name": "sign",
"type": "string",
"required": true,
"source": "query",
"description": "签名字段,兼容别名 signature(MD5 小写 hex)"
}
],
"requestBody": [
{
"name": "body",
"type": "object",
"required": true,
"source": "body",
"description": "请求体必须为 JSON;入口优先读取 rawBody,空体或非 JSON 返回 400,错误文案为 'json数据为空' 或 'json数据解析错误'。"
}
],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务码:成功通常为 1"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示消息"
},
{
"name": "data",
"type": "object",
"required": false,
"description": "接口返回数据"
},
{
"name": "timestamp",
"type": "number",
"required": true,
"description": "响应时间戳"
}
],
"errors": [
{
"code": 400,
"message": "参数缺失或错误: method/v/timestamp 或 app_key"
},
{
"code": 400,
"message": "json数据为空"
},
{
"code": 400,
"message": "json数据解析错误"
},
{
"code": 401,
"message": "app_key 无效或不可用"
},
{
"code": 401,
"message": "签名校验失败"
},
{
"code": 500,
"message": "接口错误: <message>"
}
],
"notes": [
"独立链路:/openapi 为独立入口,不依附于 system/qimen,不复用系统的请求头强校验或鉴权链。",
"不校验 platform/project 等请求头:openapi 不对 platform/project 请求头做强制校验或拒绝,headers 字段为空。",
"body 使用 JSON 解析:content-type 应包含 application/json;优先读取 ctx.request.rawBody,若未提供则回退到 ctx.request.body 或原始请求流;空体或解析失败返回 400(错误消息为 'json数据为空' 或 'json数据解析错误')。",
"app_key 校验:通过数据库表 wms_api_app(或对应模型)按 self_app_key/app_key 查询,要求 is_enabled=1 且 interface_type_id=2(OPEN_API 类型)才视为有效,否则返回 401(消息 'app_key 无效或不可用')。",
"签名规则:构建 canonicalQuery(取 query 参数,支持别名 app_key/appkey/self_app_key,签名字段支持 sign/signature;排除签名字段本身),按 key 的字母序排序并用 & 连接 key=value;计算 bodySign 为 md5(稳定序列化(body));将 canonicalQuery + self_app_secret + bodySign 连接成字符串并对该字符串计算 md5(小写 hex),结果与请求中 sign/signature 比对,匹配即通过。",
"method 分发:openapi 的 method 分发走 openapiMethods 专用目录(代码内实现独立路由/分发);已存在方法示例:index.ping(模块=基础模块)。",
"返回风格:成功与失败返回使用与系统一致的 code/message/data 格式(无需额外 flag 字段),以保证与系统端点兼容。"
]
},
{
"method": "index.ping",
"description": "基础模块 心跳接口,返回服务可用性(部署在 openapiMethods 中)",
"isNeedAuth": false,
"isNeedLogin": false,
"headers": [],
"params": [],
"response": [
{
"name": "code",
"type": "number",
"required": true,
"description": "业务状态码,成功通常为 200 或 1"
},
{
"name": "message",
"type": "string",
"required": true,
"description": "提示信息"
},
{
"name": "data",
"type": "object",
"required": false,
"description": "返回数据,ping 一般为空或包含版本/uptime 等信息"
}
],
"errors": [],
"notes": [
"模块:基础模块",
"方法部署位置:openapiMethods/index.ping"
]
}
]
}