742 lines
21 KiB
JSON
742 lines
21 KiB
JSON
{
|
|
"openapi": "3.0.3",
|
|
"info": {
|
|
"title": "ChatApp Gateway HTTP API",
|
|
"version": "1.0.0",
|
|
"description": "Gateway 对外 HTTP 接口定义，采用 OpenAPI 3.0.3，可直接导入 Apifox。该文件覆盖当前 Gateway 暴露的全部 HTTP 路由。"
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "http://127.0.0.1:8080",
|
|
"description": "本地默认地址，来源于 config/local.yaml"
|
|
}
|
|
],
|
|
"tags": [
|
|
{
|
|
"name": "System",
|
|
"description": "健康检查与就绪检查"
|
|
},
|
|
{
|
|
"name": "Auth",
|
|
"description": "用户注册"
|
|
},
|
|
{
|
|
"name": "Pay",
|
|
"description": "支付下单"
|
|
}
|
|
],
|
|
"paths": {
|
|
"/health": {
|
|
"get": {
|
|
"tags": [
|
|
"System"
|
|
],
|
|
"summary": "健康检查",
|
|
"operationId": "getHealth",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/XRequestIdHeader"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "服务存活",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ServiceStatusResponse"
|
|
},
|
|
"example": {
|
|
"status": "ok",
|
|
"service": "chatappgateway"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/heath": {
|
|
"get": {
|
|
"tags": [
|
|
"System"
|
|
],
|
|
"summary": "健康检查兼容别名",
|
|
"description": "兼容历史拼写错误的 `/heath` 路由，行为与 `/health` 完全一致。",
|
|
"operationId": "getHealthAlias",
|
|
"deprecated": true,
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/XRequestIdHeader"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "服务存活",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ServiceStatusResponse"
|
|
},
|
|
"example": {
|
|
"status": "ok",
|
|
"service": "chatappgateway"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/ready": {
|
|
"get": {
|
|
"tags": [
|
|
"System"
|
|
],
|
|
"summary": "就绪检查",
|
|
"description": "当 Gateway 可接收流量且下游依赖检查通过时返回 ready。",
|
|
"operationId": "getReady",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/XRequestIdHeader"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "服务已就绪",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ServiceStatusResponse"
|
|
},
|
|
"example": {
|
|
"status": "ready",
|
|
"service": "chatappgateway"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"503": {
|
|
"description": "服务未就绪或正在摘流",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorEnvelope"
|
|
},
|
|
"examples": {
|
|
"dependency_not_ready": {
|
|
"summary": "依赖未就绪",
|
|
"value": {
|
|
"code": "not_ready",
|
|
"message": "chatappuser not ready",
|
|
"request_id": "b31e6d8248775b9a"
|
|
}
|
|
},
|
|
"service_shutting_down": {
|
|
"summary": "服务摘流中",
|
|
"value": {
|
|
"code": "not_ready",
|
|
"message": "service is shutting down",
|
|
"request_id": "b31e6d8248775b9a"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/users/register": {
|
|
"post": {
|
|
"tags": [
|
|
"Auth"
|
|
],
|
|
"summary": "用户注册",
|
|
"description": "校验注册参数后转发到用户服务。`nickname` 为空时会自动回退为 `account`。",
|
|
"operationId": "postUserRegister",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/XRequestIdHeader"
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/RegisterRequest"
|
|
},
|
|
"example": {
|
|
"account": "demo@example.com",
|
|
"password": "secret",
|
|
"country_code": "+86",
|
|
"verify_code": "123456",
|
|
"nickname": "Neo",
|
|
"device_id": "dev-1",
|
|
"platform": "ios",
|
|
"app_version": "1.0.0"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "注册成功",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/RegisterSuccessEnvelope"
|
|
},
|
|
"example": {
|
|
"code": "ok",
|
|
"message": "ok",
|
|
"request_id": "b31e6d8248775b9a",
|
|
"data": {
|
|
"user_id": "u-100",
|
|
"access_token": "access-token",
|
|
"is_new_user": true,
|
|
"profile": {
|
|
"user_id": "u-100",
|
|
"nickname": "Neo",
|
|
"avatar_url": "https://example.com/avatar.png"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "请求参数错误",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorEnvelope"
|
|
},
|
|
"examples": {
|
|
"invalid_json": {
|
|
"summary": "JSON 非法",
|
|
"value": {
|
|
"code": "bad_request",
|
|
"message": "invalid json body",
|
|
"request_id": "b31e6d8248775b9a"
|
|
}
|
|
},
|
|
"missing_account": {
|
|
"summary": "缺少账号",
|
|
"value": {
|
|
"code": "bad_request",
|
|
"message": "account is required",
|
|
"request_id": "b31e6d8248775b9a"
|
|
}
|
|
},
|
|
"missing_password": {
|
|
"summary": "缺少密码",
|
|
"value": {
|
|
"code": "bad_request",
|
|
"message": "password is required",
|
|
"request_id": "b31e6d8248775b9a"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"description": "鉴权失败",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorEnvelope"
|
|
},
|
|
"example": {
|
|
"code": "unauthorized",
|
|
"message": "register denied",
|
|
"request_id": "b31e6d8248775b9a"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"405": {
|
|
"description": "请求方法不允许",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorEnvelope"
|
|
},
|
|
"example": {
|
|
"code": "method_not_allowed",
|
|
"message": "method not allowed",
|
|
"request_id": "b31e6d8248775b9a"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"502": {
|
|
"description": "下游服务错误",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorEnvelope"
|
|
},
|
|
"example": {
|
|
"code": "upstream_error",
|
|
"message": "user service unavailable",
|
|
"request_id": "b31e6d8248775b9a"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"504": {
|
|
"description": "下游服务超时",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorEnvelope"
|
|
},
|
|
"example": {
|
|
"code": "upstream_timeout",
|
|
"message": "upstream request timeout",
|
|
"request_id": "b31e6d8248775b9a"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/pay": {
|
|
"post": {
|
|
"tags": [
|
|
"Pay"
|
|
],
|
|
"summary": "发起支付",
|
|
"description": "校验支付参数后转发到支付服务创建支付单。",
|
|
"operationId": "postPay",
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/XRequestIdHeader"
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PayRequest"
|
|
},
|
|
"example": {
|
|
"order_no": "order-001",
|
|
"user_id": "u-100",
|
|
"amount": "9.99",
|
|
"currency": "USD",
|
|
"pay_method": "apple_pay",
|
|
"subject": "vip"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "支付单创建成功",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PaySuccessEnvelope"
|
|
},
|
|
"example": {
|
|
"code": "ok",
|
|
"message": "ok",
|
|
"request_id": "b31e6d8248775b9a",
|
|
"data": {
|
|
"payment_id": "pay-001",
|
|
"order_no": "order-001",
|
|
"user_id": "u-100",
|
|
"status": "processing",
|
|
"amount": "9.99",
|
|
"currency": "USD",
|
|
"pay_method": "apple_pay",
|
|
"subject": "vip",
|
|
"created_at": "2026-04-04T12:00:00Z"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "请求参数错误",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorEnvelope"
|
|
},
|
|
"examples": {
|
|
"invalid_json": {
|
|
"summary": "JSON 非法",
|
|
"value": {
|
|
"code": "bad_request",
|
|
"message": "invalid json body",
|
|
"request_id": "b31e6d8248775b9a"
|
|
}
|
|
},
|
|
"missing_order_no": {
|
|
"summary": "缺少订单号",
|
|
"value": {
|
|
"code": "bad_request",
|
|
"message": "order_no is required",
|
|
"request_id": "b31e6d8248775b9a"
|
|
}
|
|
},
|
|
"missing_user_id": {
|
|
"summary": "缺少用户 ID",
|
|
"value": {
|
|
"code": "bad_request",
|
|
"message": "user_id is required",
|
|
"request_id": "b31e6d8248775b9a"
|
|
}
|
|
},
|
|
"missing_amount": {
|
|
"summary": "缺少金额",
|
|
"value": {
|
|
"code": "bad_request",
|
|
"message": "amount is required",
|
|
"request_id": "b31e6d8248775b9a"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"405": {
|
|
"description": "请求方法不允许",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorEnvelope"
|
|
},
|
|
"example": {
|
|
"code": "method_not_allowed",
|
|
"message": "method not allowed",
|
|
"request_id": "b31e6d8248775b9a"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"502": {
|
|
"description": "下游支付服务错误",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorEnvelope"
|
|
},
|
|
"example": {
|
|
"code": "upstream_error",
|
|
"message": "pay service unavailable",
|
|
"request_id": "b31e6d8248775b9a"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"504": {
|
|
"description": "下游支付服务超时",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ErrorEnvelope"
|
|
},
|
|
"example": {
|
|
"code": "upstream_timeout",
|
|
"message": "upstream request timeout",
|
|
"request_id": "b31e6d8248775b9a"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"parameters": {
|
|
"XRequestIdHeader": {
|
|
"name": "X-Request-Id",
|
|
"in": "header",
|
|
"required": false,
|
|
"description": "可选链路请求 ID。不传时由 Gateway 自动生成，并在响应头与响应体中返回。",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
},
|
|
"schemas": {
|
|
"ServiceStatusResponse": {
|
|
"type": "object",
|
|
"required": [
|
|
"status",
|
|
"service"
|
|
],
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"description": "服务状态",
|
|
"example": "ok"
|
|
},
|
|
"service": {
|
|
"type": "string",
|
|
"description": "服务名称",
|
|
"example": "chatappgateway"
|
|
}
|
|
}
|
|
},
|
|
"ErrorEnvelope": {
|
|
"type": "object",
|
|
"required": [
|
|
"code",
|
|
"message",
|
|
"request_id"
|
|
],
|
|
"properties": {
|
|
"code": {
|
|
"type": "string",
|
|
"description": "业务错误码",
|
|
"example": "bad_request"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "错误描述",
|
|
"example": "account is required"
|
|
},
|
|
"request_id": {
|
|
"type": "string",
|
|
"description": "请求链路 ID",
|
|
"example": "b31e6d8248775b9a"
|
|
}
|
|
}
|
|
},
|
|
"RegisterRequest": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"account",
|
|
"password"
|
|
],
|
|
"properties": {
|
|
"account": {
|
|
"type": "string",
|
|
"description": "注册账号",
|
|
"example": "demo@example.com"
|
|
},
|
|
"password": {
|
|
"type": "string",
|
|
"description": "登录密码",
|
|
"example": "secret"
|
|
},
|
|
"country_code": {
|
|
"type": "string",
|
|
"description": "国家区号",
|
|
"example": "+86"
|
|
},
|
|
"verify_code": {
|
|
"type": "string",
|
|
"description": "验证码",
|
|
"example": "123456"
|
|
},
|
|
"nickname": {
|
|
"type": "string",
|
|
"description": "昵称；为空时服务端回退为 account",
|
|
"example": "Neo"
|
|
},
|
|
"device_id": {
|
|
"type": "string",
|
|
"description": "设备 ID",
|
|
"example": "dev-1"
|
|
},
|
|
"platform": {
|
|
"type": "string",
|
|
"description": "平台标识",
|
|
"example": "ios"
|
|
},
|
|
"app_version": {
|
|
"type": "string",
|
|
"description": "App 版本号",
|
|
"example": "1.0.0"
|
|
}
|
|
}
|
|
},
|
|
"UserProfile": {
|
|
"type": "object",
|
|
"properties": {
|
|
"user_id": {
|
|
"type": "string",
|
|
"example": "u-100"
|
|
},
|
|
"nickname": {
|
|
"type": "string",
|
|
"example": "Neo"
|
|
},
|
|
"avatar_url": {
|
|
"type": "string",
|
|
"format": "uri",
|
|
"example": "https://example.com/avatar.png"
|
|
}
|
|
}
|
|
},
|
|
"RegisterResponseData": {
|
|
"type": "object",
|
|
"properties": {
|
|
"user_id": {
|
|
"type": "string",
|
|
"example": "u-100"
|
|
},
|
|
"access_token": {
|
|
"type": "string",
|
|
"example": "access-token"
|
|
},
|
|
"is_new_user": {
|
|
"type": "boolean",
|
|
"example": true
|
|
},
|
|
"profile": {
|
|
"$ref": "#/components/schemas/UserProfile"
|
|
}
|
|
}
|
|
},
|
|
"RegisterSuccessEnvelope": {
|
|
"type": "object",
|
|
"required": [
|
|
"code",
|
|
"message",
|
|
"request_id",
|
|
"data"
|
|
],
|
|
"properties": {
|
|
"code": {
|
|
"type": "string",
|
|
"example": "ok"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"example": "ok"
|
|
},
|
|
"request_id": {
|
|
"type": "string",
|
|
"example": "b31e6d8248775b9a"
|
|
},
|
|
"data": {
|
|
"$ref": "#/components/schemas/RegisterResponseData"
|
|
}
|
|
}
|
|
},
|
|
"PayRequest": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"order_no",
|
|
"user_id",
|
|
"amount"
|
|
],
|
|
"properties": {
|
|
"order_no": {
|
|
"type": "string",
|
|
"description": "业务订单号",
|
|
"example": "order-001"
|
|
},
|
|
"user_id": {
|
|
"type": "string",
|
|
"description": "用户 ID",
|
|
"example": "u-100"
|
|
},
|
|
"amount": {
|
|
"type": "string",
|
|
"description": "金额，当前按字符串透传",
|
|
"example": "9.99"
|
|
},
|
|
"currency": {
|
|
"type": "string",
|
|
"description": "币种",
|
|
"example": "USD"
|
|
},
|
|
"pay_method": {
|
|
"type": "string",
|
|
"description": "支付方式",
|
|
"example": "apple_pay"
|
|
},
|
|
"subject": {
|
|
"type": "string",
|
|
"description": "支付主题或商品描述",
|
|
"example": "vip"
|
|
}
|
|
}
|
|
},
|
|
"PayResponseData": {
|
|
"type": "object",
|
|
"properties": {
|
|
"payment_id": {
|
|
"type": "string",
|
|
"example": "pay-001"
|
|
},
|
|
"order_no": {
|
|
"type": "string",
|
|
"example": "order-001"
|
|
},
|
|
"user_id": {
|
|
"type": "string",
|
|
"example": "u-100"
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"example": "processing"
|
|
},
|
|
"amount": {
|
|
"type": "string",
|
|
"example": "9.99"
|
|
},
|
|
"currency": {
|
|
"type": "string",
|
|
"example": "USD"
|
|
},
|
|
"pay_method": {
|
|
"type": "string",
|
|
"example": "apple_pay"
|
|
},
|
|
"subject": {
|
|
"type": "string",
|
|
"example": "vip"
|
|
},
|
|
"created_at": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"example": "2026-04-04T12:00:00Z"
|
|
}
|
|
}
|
|
},
|
|
"PaySuccessEnvelope": {
|
|
"type": "object",
|
|
"required": [
|
|
"code",
|
|
"message",
|
|
"request_id",
|
|
"data"
|
|
],
|
|
"properties": {
|
|
"code": {
|
|
"type": "string",
|
|
"example": "ok"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"example": "ok"
|
|
},
|
|
"request_id": {
|
|
"type": "string",
|
|
"example": "b31e6d8248775b9a"
|
|
},
|
|
"data": {
|
|
"$ref": "#/components/schemas/PayResponseData"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|