概述 #
Swagger 是一种用于描述 API 定义的规范,被广泛应用于定义和描述后端应用服务的API。现在,开发者后台支持导入 Swagger 3.0 的文件来创建 API 路由,包含两个入口:
- 概览页
- API路由页
Swagger 文件 Schema #
支持原生的swagger 3.0 yaml或者json文件导入开发者后台,同时支持同步至 XDP 数据服务。
1.增加扩展参数用于路由信息的创建
扩展参数 | 说明 |
---|---|
x-open-domain | 调用环境使用的域名 |
x-open-env | 上游服务的环境变量目前只支持三种: dev, uat, prd |
x-open-business | 企业内部业务线英文名称 |
x-open-application | 业务线下应用的英文名称,项目id,应用id |
x-open-version | api版本,默认使用info.version的值 |
2.为了支持多个上游服务的同时导入,对servers节点另外做出要求
...
servers:
# host为localhost或者 127.0.0.1 或者 0.0.0.0的url会被丢弃
- url: http://localhost:8080/api/v1
description: LOCALHOST
#多环境的url应该单独罗列,url是具体环境的服务地址,x-open-domain是该环境调用方的使用的域名, x-open-env是环境标量
- url: http://open.dev.datastory.com.cn/api/v1
x-open-domain: open.dev.datastory.com.cn
x-open-env: dev
- url: http://open.uat.datastory.com.cn/api/v1
x-open-domain: open.uat.datastory.com.cn
x-open-env: uat
- url: https://open.datastory.com.cn/api/v1
x-open-domain: open.datastory.com.cn
x-open-env: prd
...
3.其他无效 Swagger 字段说明
...
#info信息用于路由命名以及uri的构建,
#路由命名: ${upstreamId}.${path.operationId}
#uri构建:
#/${x-open-company}.${x-open-business}.${x-open-application}
#/${x-open-version}
#/${server.x-open-env}
#/${path.url.replaceAll("/", ".").replaceAll(/{[a-zA-Z0-9\-\_]*}/g, "*")}
info:
title: 方舟API
x-open-company: datastory
x-open-business: matrix
x-open-application: projectId
x-open-version: 1.0.0
...
...
paths:
/users:
get:
summary: Get a user by ID
# 这部份信息会被忽略
parameters:
- in: path
name: userId
schema:
type: integer
required: true
description: Numeric ID of the user to get
...
...
paths:
/hello:
get:
description: hello world.
operationId: hello
# 这部份信息会被忽略
responses:
'200':
description: list response
default:
description: unexpected error
...
...
paths:
/hello:
get:
description: hello world.
operationId: hello
# 这部份信息会被忽略
requestBody:
content:
application/json:
schema: $ref: '#/components/schemas/UpdateJourneyRequest'
...
4.Swagger 字段映射说明
paths:
/hello: # 路由 uri
get: # 路由 method
suumary: hello world. # 路由描述
operationId: hello # 路由名称
responses:
'200':
description: list response
default:
description: unexpected error
示例 #
openapi: 3.0.3
info:
title: CEM APIs
description: CEM APIs
version: 0.0.1-SNAPSHOT
x-open-company: datastory
x-open-business: matrix
x-open-application: cem.redpacket
externalDocs:
description: Check the source code here
url: https://git.datastory.com.cn/ds-matrix/ds-matrix-api-specification.git
servers:
- url: http://cem-xdp.datastory.com.cn
x-open-domain: cem-xdp.datastory.com.cn
x-open-env: dev
description: dev.datastory.com.cn
- url: https://uat-cem.datastory.com.cn/redpacket
x-open-domain: uat-cem.datastory.com.cn
x-open-env: uat
- url: https://cem.datastory.com.cn/redpacket
x-open-domain: cem.datastory.com.cn
x-open-env: prd
paths:
/deposits:
post:
summary: '问卷红包充值记录创建'
operationId: CreateDeposit
tags:
- Redpackets -- 红包
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDepositRequest'
responses:
'201':
description: '下单成功'
content:
application/json:
schema:
$ref: '#/components/schemas/Deposit'
'500':
$ref: '#/components/responses/Fault'
'400':
$ref: '#/components/responses/Error'
get:
summary: '问卷红包充值记录检索'
operationId: ListDeposit
tags:
- Redpackets -- 红包
parameters:
- $ref: '#/components/parameters/SurveyIdParam'
responses:
'200':
description: '检索成功'
content:
application/json:
schema:
$ref: '#/components/schemas/DepositResponse'
'500':
$ref: '#/components/responses/Fault'
'400':
$ref: '#/components/responses/Error'
/deposits/{id}:
get:
summary: '红包充值结果查询'
operationId: GetDeposit
tags:
- Redpackets -- 红包
parameters:
- $ref: '#/components/parameters/DepositIdParam'
responses:
'200':
description: '获取成功'
content:
application/json:
schema:
$ref: '#/components/schemas/Deposit'
'500':
$ref: '#/components/responses/Fault'
'400':
$ref: '#/components/responses/Error'
/surveys/{id}/redpacketConfig:
get:
summary: '查看问卷红包设置'
operationId: GetSurveyRedpacketConfig
parameters:
- name: id
description: '问卷ID'
in: path
schema:
type: string
required: true
responses:
'200':
description: '问卷红包设置'
content:
application/json:
schema:
$ref: '#/components/schemas/Config'
'500':
$ref: '#/components/responses/Fault'
default:
$ref: '#/components/responses/Error'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
responses:
Fault:
description: '服务内部错误, 请联系管理员'
content:
application/json:
schema:
$ref: '#/components/schemas/FaultBody'
Error:
description: |
用户请求错误, 包括: 401,402,403,40x等
---
错误码列表:
| id | code | message |
|----|------|---------|
|40016|InvalidLotteryTicket|无效的中奖券码|
|40021|LotteryTicketTimeout|中奖券码已过期|
|40022|LotteryTicketVerified|中奖券码已领取|
|40029|InvalidLotterySubmitId|无效的抽奖券码|
|40034|RedpacketReceiveTimesExceeds|红包领取机会已用完|
content:
application/json:
schema:
type: object
properties:
error:
$ref: '#/components/schemas/ErrorBody'
required: [ error ]
UnauthorizedError:
description: '未认证成功错误'
content:
application/json:
schema:
type: object
properties:
error:
$ref: '#/components/schemas/ErrorBody'
required: [ error ]
schemas:
CreateDepositRequest:
description: '问卷添加红包'
properties:
surveyId:
type: string
description: "问卷ID"
amount:
type: integer
format: int64
description: "红包总额,单位分"
minimum: 1
quantity:
type: integer
description: "红包数量,单位个"
minimum: 1
type:
type: string
description: "红包类型,FIXED固定金额,RANDOM随机金额"
enum: [ "FIXED", "RANDOM" ]
amountRandomMin:
type: integer
format: int64
description: "随机红包最小金额,单位分"
minimum: 1
amountRandomMax:
type: integer
format: int64
description: "随机红包最大金额,单位分"
minimum: 1
required: [ surveyId, amount, quantity, type ]
Deposit:
description: '红包充值记录'
properties:
id:
type: string
description: '充值记录ID'
surveyId:
type: string
description: "问卷ID"
amount:
type: integer
format: int64
description: "充值总额,单位分"
minimum: 1
quantity:
type: integer
description: "充值金额可发放红包总数量,单位个"
minimum: 1
type:
type: string
description: "红包类型,FIXED固定金额,RANDOM随机金额"
enum: [ "FIXED", "RANDOM" ]
amountRandomMin:
type: integer
format: int64
description: "随机红包最小金额,单位分"
minimum: 10
amountRandomMax:
type: integer
format: int64
description: "随机红包最大金额,单位分"
minimum: 10
state:
type: string
description: '充值记录状态'
# TODO: 具体的状态待细化
enum: [ 'UNPAID', 'COMPLETED', 'CLOSED', 'REFUNDED' ]
paymentId:
type: string
description: '付款单号'
refundId:
type: string
description: '退款单号'
createdAt:
type: integer
format: int64
description: "下单时间,时间戳"
distributionSummary:
$ref: '#/components/schemas/DistributionSummary'
DepositResponse:
description: '红包充值金额记录列表'
properties:
deposits:
type: array
items:
$ref: '#/components/schemas/Deposit'
LotteriesVerifyResponse:
description: '中奖红包领取情况响应'
properties:
state:
description: '中奖红包状态 DISTRIBUTED-待领取,AUDITING-待审核,GRANTED-发放中, COMPLETED-已领取,CANCELED-已取消, TIMEOUT-超时'
type: string
enum: [ 'DISTRIBUTED', 'GRANTED', 'AUDITING', 'COMPLETED', 'CANCELED', 'TIMEOUT' ]
LotteryReceiveRequest:
description: '中奖红包领取'
type: object
properties:
code:
description: 'oauth授权code'
type: string
userName:
description: '用户名'
type: string
avatarUrl:
description: '用户头像'
type: string
required: ['code', 'userName', 'avatarUrl']
DrawLotteryResponse:
description: '红包抽奖响应'
properties:
ticket:
description: '领奖凭证'
type: string
qrCodeImg:
description: '中奖红包领取二维码图片, base64格式'
type: string
RefundDepositRequest:
description: '问卷剩余红退款请求'
properties:
surveyId:
description: '问卷ID'
type: string
required: [ surveyId ]
ConfigConfig:
description: "红包设置JSON"
type: object
properties:
enabled:
description: '是否投放红包'
type: string
enum: [ 'TRUE', 'FALSE' ]
channels:
description: '红包允许投放渠道'
type: array
items:
type: string
enum: [ 'URL','SMS','EMAIL' ]
lottery:
description: '中奖设置'
properties:
type:
description: '中奖类型,固定概率 or 固定人数(每多少人会中奖)'
type: string
enum: [ 'FIXED_PROBABILITY', 'FIXED_NUMBER' ]
probability:
description: '中奖概率,从1到100,单位百分号'
type: integer
minimum: 1
maximum: 100
enop:
description: 'Every Number Of People的缩写,暂时最大支持1k人'
type: integer
minimum: 1
maximum: 1000
security:
description: '安全设置'
properties:
distributionMode:
description: '红包发放模式,暂时必须要审核'
type: string
enum: [ 'AUDIT' ]
verification:
description: '是否开启验证码,当前必须开启'
type: boolean
enum: [ True ]
display:
description: '红包现实设置'
properties:
name:
description: '红包发送者名词,限制10个中文'
type: string
minimum: 1
maximum: 10
tips:
description: '提示信息'
type: string
minimum: 1
maximum: 50
required: [ 'enabled', 'channels' ]
Config:
description: '问卷红包设置'
properties:
id:
description: '红包设置ID'
type: string
config:
$ref: '#/components/schemas/ConfigConfig'
UpdateConfigRequest:
$ref: '#/components/schemas/ConfigConfig'
DistributionSummary:
description: '红包发放汇总数据'
properties:
distributedQuantity:
description: '已发放,但未审核红包数'
type: integer
distributedAmount:
description: '已发放,但未审核金额,单位分'
type: integer
format: int64
grantedQuantity:
description: '已发放,且已通过审核放红包数'
type: integer
grantedAmount:
description: '已发放,且已通过审核金额,单位分'
type: integer
format: int64
arrivedQuantity:
description: '已到帐红包数'
type: integer
arrivedAmount:
description: '已到帐红包金额,单位分'
type: integer
format: int64
refundedAmount:
description: '已退款金额,单位分'
type: integer
format: int64
Distribution:
description: '红包发放记录'
properties:
id:
description: '发放记录ID'
type: string
surveyId:
description: '问卷ID'
type: string
depositId:
description: '红包充值记录ID'
type: string
submitId:
description: '答卷提交ID'
type: string
submitTime:
description: '答卷提交时间'
type: integer
format: int64
submitDuration:
description: '答卷时长'
type: integer
format: int64
uid:
description: '用户ID,对应于微信,则为openid'
type: string
userName:
description: '用户名'
type: string
avatarUrl:
description: '头像url'
type: string
amount:
description: '红包领取金额'
type: integer
format: int64
lotteryTicket:
description: '抽奖券码'
type: string
createdAt:
description: '红包发放记录创建取时间'
type: integer
format: int64
auditedAt:
description: '红包发放记录审核时间'
type: integer
format: int64
completedAt:
description: '红包成功发放至用户零钱时间'
type: integer
format: int64
grantedAt:
description: '红包发放记录失效时间'
type: integer
format: int64
state:
description: 'DISTRIBUTED(生成发放记录),AUDITING(审核中),GRANTED(已发放),COMPLETED(已领取红包/转账成功),CANCELED(审核不通过),TIMEOUT(超时)'
type: string
enum: ['DISTRIBUTED', 'AUDITING', 'GRANTED', 'COMPLETED', 'CANCELED', 'TIMEOUT' ]
ip:
description: '中奖ip'
type: string
DistributionsResponse:
description: '红包发放记录响应'
type: object
properties:
distributions:
type: array
items:
$ref: '#/components/schemas/Distribution'
pagination:
$ref: '#/components/schemas/Pagination'
PayDepositResponse:
description: '红包付款响应'
properties:
codeUrl:
type: string
description: '支付二维码链接'
BatchGrantDistributionRequest:
description: '批量发放红包接口'
type: object
properties:
distributionIds:
type: array
items:
type: string
BatchCancelDistributionRequest:
description: '批量取消红包接口'
type: object
properties:
distributionIds:
type: array
items:
type: string
DrawLotteryRequest:
description: '红包抽奖请求。'
type: object
properties:
submitId:
description: '问卷提交ID'
type: string
surveyId:
description: '问卷ID'
type: string
channel:
description: '问卷投放渠道10-URL, 20-SMS, 30-EMAIL'
type: string
enum: ['10', '20', '30']
ticket:
description: '抽奖ticket,问卷提交成功后,会发放个ticket,一次性有效'
type: string
required: ['submitId', 'surveyId']
Pagination:
description: '分页'
type: object
properties:
index:
type: integer
description: '当前页'
limit:
type: integer
description: '每页数量'
total:
type: integer
format: int64
description: '总数'
ErrorBody:
type: object
properties:
code:
type: string
id:
type: string
message:
type: string
target:
type: string
details:
type: array
items:
type: object
required: [ code, id, message ]
FaultBody:
type: object
properties:
code:
type: string
default: "InternalFault"
message:
type: string
default: "服务内部错误, 请联系管理员"
parameters:
SurveyIdParam:
name: surveyId
description: '问卷ID'
in: query
schema:
type: string
required: true
DepositIdParam:
name: id
description: '充值记录ID'
in: path
schema:
type: string
required: true
DistributionIdParam:
name: id
description: '发放记录ID'
in: path
required: true
schema:
type: string
IndexParam:
name: index
in: query
description: "当前页"
schema:
type: integer
minimum: 1
default: 1
LimitParam:
name: limit
in: query
description: "每页数量"
schema:
type: integer
default: 10