poa-api-docs/api-docs/user-data-service-thirdparty-poa.v1.yaml

# user-data-service-thirdparty-poa.v1.yaml
#
# 1. 创建服务
# curl -i -s -X POST 'https://poa-sa.dev.supwisdom.com/v1/services' -H 'Content-Type: application/json' -d '{"id": "userThirdparty", "origin": "http://user-data-service-poa-svc.user-data-service.svc.cluster.local:8080", "name": "用户服务（第三方应用）", "description": "用户服务（第三方应用）"}'
# https://user-api.supwisdom.com
#
# 2. 创建版本
# curl -i -s -X POST 'https://poa-sa.dev.supwisdom.com/v1/services/userThirdparty/apiVersions/v1'
#
# 3. 上传OAS Yaml
# curl -i -s -X POST 'https://poa-sa.dev.supwisdom.com/v1/services/userThirdparty/apiVersions/v1/apiSpecs' -H 'Content-Type: application/yaml' --data-binary @user-data-service-thirdparty-poa.v1.yaml
#
# 4. 发布版本
# curl -i -s -X POST 'https://poa-sa.dev.supwisdom.com/v1/services/userThirdparty/apiVersions/v1/publish'
#
openapi: 3.0.2
info:
  title: User Data Service (Third Party) Platform Open APIs
  version: v1
  description: '用户服务（第三方应用） - 平台开放接口'
servers:
  - url: '${POA_SERVER_URL}/apis/userThirdparty/v1'
    description: '生产环境'
tags:
  - name: AdminAppGroup
    description: '应用的用户组（普通）管理'

paths:

  '/admin/application/{applicationId}/groups':
    post:
      summary: 创建应用的用户组（普通）
      operationId: createAppGroup
      tags:
        - AdminAppGroup
      security:
        - oauth2:
          - "userThirdparty:v1:adminAppGroupWrite"
      parameters:
        - name: applicationId
          in: path
          required: true
          description: 应用标识
          schema:
            type: string
      requestBody:
        description: 用户组（普通）创建请求
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminAppGroupCreateRequest'
      responses:
        '200':
          description: 用户组（普通）创建响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminAppGroupCreateResponse'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/admin/application/{applicationId}/groups/{groupId}':
    get:
      summary: 获取应用的用户组（普通）
      operationId: getAppGroup
      tags:
        - AdminAppGroup
      security:
        - oauth2:
          - "userThirdparty:v1:adminAppGroupWrite"
      parameters:
        - name: applicationId
          in: path
          required: true
          description: 应用标识
          schema:
            type: string
        - name: groupId
          in: path
          required: true
          description: 用户组ID
          schema:
            type: string
      responses:
        '200':
          description: 用户组（普通）获取响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminAppGroupGetResponse'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

    put:
      summary: 获取应用的用户组（普通）
      operationId: updateAppGroup
      tags:
        - AdminAppGroup
      security:
        - oauth2:
          - "userThirdparty:v1:adminAppGroupWrite"
      parameters:
        - name: applicationId
          in: path
          required: true
          description: 应用标识
          schema:
            type: string
        - name: groupId
          in: path
          required: true
          description: 用户组ID
          schema:
            type: string
      requestBody:
        description: 用户组（普通）更新请求
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminAppGroupUpdateRequest'
      responses:
        '200':
          description: 用户组（普通）获取响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminAppGroupUpdateResponse'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

    delete:
      summary: 删除应用的用户组（普通）
      operationId: deleteAppGroup
      tags:
        - AdminAppGroup
      security:
        - oauth2:
          - "userThirdparty:v1:adminAppGroupWrite"
      parameters:
        - name: applicationId
          in: path
          required: true
          description: 应用标识
          schema:
            type: string
        - name: groupId
          in: path
          required: true
          description: 用户组ID
          schema:
            type: string
      responses:
        '200':
          description: 用户组（普通）删除响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminAppGroupDeleteResponse'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'


  '/admin/application/{applicationId}/groups/{groupId}/accounts':
    post:
      summary: 关联应用的用户组（普通）帐号
      operationId: relateAppGroupAccounts
      tags:
        - AdminAppGroup
      security:
        - oauth2:
          - "userThirdparty:v1:adminAppGroupWrite"
      parameters:
        - name: applicationId
          in: path
          required: true
          description: 应用标识
          schema:
            type: string
        - name: groupId
          in: path
          required: true
          description: 用户组ID
          schema:
            type: string
      requestBody:
        description: 用户组（普通）关联帐号请求
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminAppGroupRelateAccountsRequest'
      responses:
        '200':
          description: 用户组（普通）关联帐号响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminAppGroupRelateAccountsResponse'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'


components:

  # Security Schemes
  
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: ${POA_SERVER_URL}/oauth2/token
          scopes:
            "userThirdparty:v1:adminAppGroupWrite": "写入应用的用户组（普通）"


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

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


  schemas:
  
    # Error
    
    ErrorResponse:
      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

    # DictionaryType:
    #   title: 实体 - 字典
    #   allOf:
    #     - $ref: '#/components/schemas/BaseEntity'
    #     - type: object
    #       title: 实体属性
    #       properties:
    #         code:
    #           title: 代码
    #           type: string
    #         name:
    #           title: 名称
    #           type: string
    #         enable:
    #           title: 是否启用
    #           type: boolean
    #           default: true
    #         sort:
    #           title: 排序
    #           type: integer
    #           format: int64
    #         multiLevel:
    #           title: 是否多层级
    #           type: boolean

    Dictionary:
      title: 实体 - 字典
      allOf:
        - $ref: '#/components/schemas/BaseEntity'
        - type: object
          title: 实体属性
          properties:
            code:
              title: 代码
              type: string
            name:
              title: 名称
              type: string
            enable:
              title: 是否启用
              type: boolean
              default: true
            sort:
              title: 排序
              type: integer
              format: int64
            # dictionaryType:
            #   title: 字典类型
            #   allOf:
            #     - $ref: '#/components/schemas/DictionaryType'
            # parentDictionary:
            #   title: 父字典
            #   allOf:
            #     - $ref: '#/components/schemas/Dictionary'


    Group:
      title: 实体 - 用户组
      allOf:
        - $ref: '#/components/schemas/BaseEntity'
        - type: object
          title: 实体属性
          properties:
            code:
              title: 代码
              type: string
            name:
              title: 名称
              type: string
            description: 
              title: 描述
              type: string
            type: 
              title: 类型
              type: string
            state: 
              title: 状态（0：正常，1：冻结，2：注销）
              type: integer
              format: int32
            sort:
              title: 排序
              type: integer
              format: int32
            isDataCenter:
              title: 是否来源数据中心
              type: boolean
            common:
              title: 是否公共
              type: boolean
            category:
              title: 类别
              allOf:
                - $ref: '#/components/schemas/Dictionary'
            applicationId:
              title: 所属应用标识
              type: string
            businessDomainId:
              title: 所属业务域ID
              type: string
            systemId: 
              title: 所属系统ID
              type: string


    # Request VO
    AdminAppGroupCreateRequest:
      title: 用户组（普通）创建请求
      properties:
        code:
          title: 代码
          type: string
        name:
          title: 名称
          type: string
        description:
          title: 描述
          type: string
        state:
          title: 状态（0：正常，1：冻结，2：注销）
          type: integer
          format: int32
        categoryCode:
          title: 类别（字典代码）
          type: string


    AdminAppGroupUpdateRequest:
      title: 用户组（普通）更新请求
      properties:
        code:
          title: 代码
          type: string
        name:
          title: 名称
          type: string
        description:
          title: 描述
          type: string
        state:
          title: 状态（0：正常，1：冻结，2：注销）
          type: integer
          format: int32
        categoryCode:
          title: 类别（字典代码）
          type: string


    AdminAppGroupRelateAccountsRequest:
      title: 用户组（普通）关联帐号请求
      properties:
        addAccountIds:
          title: 添加的帐号IDs
          type: array
          items: 
            title: 账号Id
            type: string
        delAccountIds:
          title: 移除的帐号IDs
          type: array
          items: 
            title: 账号Id
            type: string


    # Response VO

    AbstractApiResponse:
      title: 响应
      properties:
        code:
          title: 响应代码
          type: integer
          format: int32
          default: 0
        message:
          title: 响应信息
          type: string
    DefaultApiResponse:
      allOf:
        - $ref: '#/components/schemas/AbstractApiResponse'
        - type: object
          title: 响应数据
          properties:
            data:
              title: 响应数据
              type: object



    AdminAppGroupGetResponse:
      allOf:
      - $ref: '#/components/schemas/DefaultApiResponse'
      - type: object
        title: 响应数据
        properties:
          data:
            allOf:
            - type: object
              title: 结果
              properties:
                message:
                  title: 结果说明
                  type: string
                group:
                  title: 用户组（普通）
                  allOf:
                    - $ref: '#/components/schemas/Group'

    AdminAppGroupCreateResponse:
      allOf:
      - $ref: '#/components/schemas/DefaultApiResponse'
      - type: object
        title: 响应数据
        properties:
          data:
            allOf:
            - type: object
              title: 结果
              properties:
                message:
                  title: 结果说明
                  type: string
                group:
                  title: 用户组（普通）
                  allOf:
                    - $ref: '#/components/schemas/Group'

    AdminAppGroupUpdateResponse:
      allOf:
      - $ref: '#/components/schemas/DefaultApiResponse'
      - type: object
        title: 响应数据
        properties:
          data:
            allOf:
            - type: object
              title: 结果
              properties:
                message:
                  title: 结果说明
                  type: string
                group:
                  title: 用户组（普通）
                  allOf:
                    - $ref: '#/components/schemas/Group'


    AdminAppGroupDeleteResponse:
      allOf:
      - $ref: '#/components/schemas/DefaultApiResponse'
      - type: object
        title: 响应数据
        properties:
          data:
            allOf:
            - type: object
              title: 结果
              properties:
                message:
                  title: 结果说明
                  type: string


    AdminAppGroupRelateAccountsResponse:
      allOf:
      - $ref: '#/components/schemas/DefaultApiResponse'
      - type: object
        title: 响应数据
        properties:
          data:
            allOf:
            - type: object
              title: 结果
              properties:
                message:
                  title: 结果说明
                  type: string