概述

Swagger 是一种用于描述 API 定义的规范，被广泛应用于定义和描述后端应用服务的API。现在，开发者后台支持导入 Swagger 3.0 的文件来创建 API 路由，包含两个入口：

1. 概览页

1. API路由页

Swagger 文件 Schema

支持原生的swagger 3.0 yaml或者json文件导入开发者后台，同时支持同步至 XDP 数据服务。

1.增加扩展参数用于路由信息的创建

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