poa-api-docs/api-docs/communicate-center-poa.v1.yaml

# communicate-center-poa.v1.yaml
#
# 1. 创建服务
# curl -i -s -X POST 'https://poa-sa.dev.supwisdom.com/v1/services' -H 'Content-Type: application/json' -d '{"id": "communicate", "origin": "http://communicate-center-poa-svc.communicate-center.svc.cluster.local:8080", "name": "通信服务", "description": "通信服务"}'
#
# 2. 创建版本
# curl -i -s -X POST 'https://poa-sa.dev.supwisdom.com/v1/services/communicate/apiVersions/v1'
#
# 3. 上传OAS Yaml
# curl -i -s -X POST 'https://poa-sa.dev.supwisdom.com/v1/services/communicate/apiVersions/v1/apiSpecs' -H 'Content-Type: application/yaml' --data-binary @communicate-center-poa.v1.yaml
#
# 4. 发布版本
# curl -i -s -X POST 'https://poa-sa.dev.supwisdom.com/v1/services/communicate/apiVersions/v1/publish'
#
openapi: 3.0.2
info:
  title: Communicate Center Platform Open APIs
  version: v1
  description: '通信服务 - 平台开放接口'
servers:
  - url: '${POA_SERVER_URL}/apis/communicate/v1'
    description: '正式环境'
tags:
  - name: Communication
    description: '通信'
paths:

  '/communications/{communicationLogId}/sendStatus':
    get:
      summary: 检查发送状态
      description: 检查发送状态
      operationId: checkSendStatus
      tags:
        - Communication
      security:
        - oauth2:
          - "communicate:v1:communicationCheck"
      parameters:
        - name: communicationLogId
          in: path
          required: true
          description: 通信记录ID
          schema:
            type: string
      responses:
        '200':
          description: 发送状态
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationSendResponse'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/communications/sendMail':
    post:
      summary: 发送邮件
      description: 发送邮件
      operationId: sendMail
      tags:
        - Communication
      security:
        - oauth2:
          - "communicate:v1:communicationSend"
      requestBody:
        description: 发送请求数据
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommunicationSendRequest'
      responses:
        '200':
          description: 发送状态
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationSendResponse'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'


  '/communications/sendSms':
    post:
      summary: 发送短信
      description: 发送短信
      operationId: sendSms
      tags:
        - Communication
      security:
        - oauth2:
          - "communicate:v1:communicationSend"
      requestBody:
        description: 发送请求数据
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommunicationSendRequest'
      responses:
        '200':
          description: 发送状态
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunicationSendResponse'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'





components:

  # Security Schemes
  
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: ${POA_SERVER_URL}/oauth2/token
          scopes:
            "communicate:v1:communicationCheck": "检查"
            "communicate:v1:communicationSend": "发送"


  responses:
    'ErrorResponse400':
      description: unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'

    DefaultErrorResponse:
      description: unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'

  schemas:
  
    # Error
    
    ApiErrorResponse:
      title: '异常响应'
      required:
        - code
        - message
      properties:
        code:
          title: 异常代码
          type: integer
          format: int32
          default: -1
        message:
          title: 异常信息
          type: string
          default: "未知错误"

    # Entity
    
    BaseEntity:
      title: 实体 - 基类
      type: object
      properties:
        id:
          title: ID
          type: string
        #companyId:
        #  title: 'Company ID, 固定 1'
        #  type: string
        #  default: '1'
        #deleted:
        #  title: 是否删除
        #  type: boolean
        #  default: false
        #addAccount:
        #  title: 创建人
        #  type: string
        #addTime:
        #  title: 创建时间
        #  type: string
        #  format: date-time
        #editAccount:
        #  title: 修改人
        #  type: string
        #editTime:
        #  title: 修改时间
        #  type: string
        #  format: date-time
        #deleteAccount:
        #  title: 删除人
        #  type: string
        #deleteTime:
        #  title: 删除时间
        #  type: string
        #  format: date-time


    # DTO
    Communication: 
      title: DTO - 通信数据
      type: object
      properties:
        from:
          title: 来源
          type: string
        to:
          title: 接收帐号
          type: string
        payload:
          title: 数据载荷
          allOf:
            - $ref: '#/components/schemas/CommunicationPayload'

    CommunicationPayload:
      title: DTO - 通信数据载荷
      type: object
      properties:
        subject:
          title: 主题
          type: string
        template:
          title: 模板
          type: string
        data:
          title: 数据（Map<String, String>）
          type: object
          additionalProperties:
            type: string

          # type: array
          # items: 
          #   title: 数据项
          #   type: object
          #   properties:
          #     key:
          #       title: 键
          #       type: string
          #     value: 
          #       title: 值
          #       type: string


    # Request VO
    CommunicationSendRequest:
      title: 请求数据 - 发送请求
      allOf:
        - $ref: '#/components/schemas/Communication'


    # Response Data
    CommunicationSendResponseData:
      title: 响应数据 - 发送响应
      type: object
      properties:
        sendStatus:
          title: 发送状态
          type: string
        sendResult:
          title: 发送结果
          type: string


    # Response VO

    ApiDataResponse:
      title: 响应
      properties:
        code:
          title: 响应代码
          type: integer
          format: int32
          default: 0
        message:
          title: 响应信息
          type: string
        data:
          title: 响应数据
          type: object

    DefaultApiDataResponse:
      allOf:
        - $ref: '#/components/schemas/ApiDataResponse'
        - type: object
          title: 响应
          properties:
            data:
              title: 响应数据
              type: object

    CommunicationSendResponse:
      allOf:
        - $ref: '#/components/schemas/DefaultApiDataResponse'
        - type: object
          title: 响应
          properties:
            data:
              allOf:
                - $ref: '#/components/schemas/CommunicationSendResponseData'