poa-api-docs/api-docs/user-authorization-service-poa.v1.yaml

# user-authorization-service-poa.v1.yaml
#
# 1. 创建服务
# curl -i -s -X POST 'https://poa-sa.supwisdom.com/v1/services' -H 'Content-Type: application/json' -d '{"id": "authz", "origin": "http://user-authorization-poa-svc.user-authorization-service.svc.cluster.local:8080", "name": "授权服务", "description": "授权服务"}'
#
# 2. 创建版本
# curl -i -s -X POST 'https://poa-sa.supwisdom.com/v1/services/authz/apiVersions/v1'
#
# 3. 上传OAS Yaml
# curl -i -s -X POST 'https://poa-sa.supwisdom.com/v1/services/authz/apiVersions/v1/apiSpecs' -H 'Content-Type: application/yaml' --data-binary @user-authorization-service-poa.v1.yaml
#
# 4. 发布版本
# curl -i -s -X POST 'https://poa-sa.supwisdom.com/v1/services/authz/apiVersions/v1/publish'
#
openapi: 3.0.2
info:
  title: User Authorization Service Platform Open APIs
  version: v1
  description: '用户授权服务 - 平台开放接口'
servers:
  - url: '${POA_SERVER_URL}/apis/authz/v1'
    description: '生产环境'
tags:
  - name: Role
    description: '角色'
paths:

  '/application/{applicationId}/roles':
    get:
      summary: 获取应用下的角色列表
      description: 获取应用下的角色列表
      operationId: loadApplicationRoles
      tags:
        - Role
      security:
        - oauth2:
          - "authz:v1:readRole"
      parameters:
        - name: applicationId
          in: path
          required: true
          description: 应用标识
          schema:
            type: string
      responses:
        '200':
          description: 角色列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationRolesResponse'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'


  '/application/{applicationId}/role/{rolecode}/accounts':
    get:
      summary: 获取应用下的一个角色的用户帐号
      description: 获取应用下的一个角色的用户帐号
      operationId: loadApplicationRoleAccounts
      tags:
        - Role
      security:
        - oauth2:
          - "authz:v1:readRole"
      parameters:
        - name: applicationId
          in: path
          required: true
          description: 应用标识
          schema:
            type: string
        - name: rolecode
          in: path
          required: true
          description: 角色代码
          schema:
            type: string
        - name: loadAll
          in: query
          required: false
          description: 分页-是否返回所有（当为 true 时，不分页，参数 pageIndex、pageSize 无效）
          schema:
            type: boolean
            default: false
        - name: pageIndex
          in: query
          required: false
          description: 分页-页码
          schema:
            type: integer
            format: int32
            default: 0
        - name: pageSize
          in: query
          required: false
          description: 分页-每页记录数
          schema:
            type: integer
            format: int32
            default: 1000
      responses:
        '200':
          description: 用户的帐号ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationRoleAccountsResponse'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/application/{applicationId}/account/{username}/roles':
    get:
      summary: 获取用户帐号在某一应用下所拥有的角色
      description: 获取用户帐号在某一应用下所拥有的角色
      operationId: loadAccountApplicationRoles
      tags:
        - Role
      security:
        - oauth2:
          - "authz:v1:readRole"
      parameters:
        - name: applicationId
          in: path
          required: true
          description: 应用标识
          schema:
            type: string
        - name: username
          in: path
          required: true
          description: 用户名
          schema:
            type: string
      responses:
        '200':
          description: 角色列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountApplicationRolesResponse'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'

  '/application/{applicationId}/roles/accounts':
    post:
      summary: 获取应用下的多个角色的用户帐号
      description: 获取应用下的多个角色的用户帐号
      operationId: loadAccountsByApplicationRole
      tags:
        - Role
      security:
        - oauth2:
          - "authz:v1:readRole"
      parameters:
        - name: applicationId
          in: path
          required: true
          description: 应用标识
          schema:
            type: string
        - name: loadAll
          in: query
          required: false
          description: 分页-是否返回所有（当为 true 时，不分页，参数 pageIndex、pageSize 无效）
          schema:
            type: boolean
            default: false
        - name: pageIndex
          in: query
          required: false
          description: 分页-页码
          schema:
            type: integer
            format: int32
            default: 0
        - name: pageSize
          in: query
          required: false
          description: 分页-每页记录数
          schema:
            type: integer
            format: int32
            default: 1000
      requestBody:
        description: 角色ID
        required: true
        content:
          application/json:
            schema:
              type: array
              items: 
                title: 角色ID
                type: string
      responses:
        '200':
          description: 用户的帐号ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationRolesAccountsResponse'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'


  '/application/{applicationId}/role/{rolecode}/groups':
    get:
      summary: 获取应用下的一个角色关联的用户组
      description: 获取应用下的一个角色关联的用户组
      operationId: loadApplicationRoleGroups
      tags:
        - Role
      security:
        - oauth2:
          - "authz:v1:readRole"
      parameters:
        - name: applicationId
          in: path
          required: true
          description: 应用标识
          schema:
            type: string
        - name: rolecode
          in: path
          required: true
          description: 角色代码
          schema:
            type: string
        - name: groupType
          in: path
          required: false
          description: 用户组类型（1 普通，2 岗位）
          schema:
            type: string
      responses:
        '200':
          description: 角色关联的用户组列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationRoleGroupsResponse'
        default:
          $ref: '#/components/responses/DefaultErrorResponse'


components:

  # Security Schemes
  
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: ${POA_SERVER_URL}/oauth2/token
          scopes:
            "authz:v1:readRole": "读取角色"

  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
        #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

    User:
      title: 实体 - 用户
      allOf:
        - $ref: '#/components/schemas/BaseEntity'
        - type: object
          title: 实体属性
          properties:
            username:
              title: 代码
              type: string
            name:
              title: 姓名
              type: string

    Role:
      title: 实体 - 角色
      allOf:
        - $ref: '#/components/schemas/BaseEntity'
        - type: object
          title: 实体属性
          properties:
            applicationId:
              title: 所属应用
              type: string
            code:
              title: 代码
              type: string
            name:
              title: 名称
              type: string
            description:
              title: 描述
              type: string
            enabled:
              title: 是否可用
              type: boolean
            externalId:
              title: 扩展ID
              type: string


    GroupModel:
      title: 模型 - 用户组
      allOf:
        - type: object
          title: 实体属性
          properties:
            id:
              title: ID
              type: string
            applicationId:
              title: 所属应用
              type: string
            code:
              title: 代码
              type: string
            name:
              title: 名称
              type: string
            description:
              title: 描述
              type: string
            type:
              title: 类型，1 普通用户组，2 岗位用户组
              type: string
            state:
              title: 状态，0:正常 1:冻结 2:注销
              type: integer
              format: int32
            sort:
              title: 排序
              type: integer
              format: int32
            common:
              title: 是否公共
              type: boolean

    # Request VO


    # Response Data


    # Response VO

    AbstractApiResponse:
      title: 响应
      properties:
        acknowleged:
          title: 响应结果（废弃，请使用code）
          type: boolean
          default: true
        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



    ApplicationRolesResponse:
      allOf:
        - $ref: '#/components/schemas/DefaultApiResponse'
        - type: object
          title: 响应数据
          properties:
            data:
              allOf:
              - type: object
                title: 数据
                properties:
                  applicationId:
                    title: 应用标识
                    type: string
                  roles:
                    title: 角色数据
                    type: array
                    items:
                      $ref: '#/components/schemas/Role'


    ApplicationRoleAccountsResponse:
      allOf:
        - $ref: '#/components/schemas/DefaultApiResponse'
        - type: object
          title: 响应数据
          properties:
            data:
              allOf:
              - type: object
                title: 数据
                properties:
                  applicationId:
                    title: 应用标识
                    type: string
                  rolecode:
                    title: 角色代码
                    type: string
                  accounts:
                    title: 用户帐号数据
                    type: array
                    items:
                      title: 用户的帐号ID
                      type: string


    AccountApplicationRolesResponse:
      allOf:
        - $ref: '#/components/schemas/DefaultApiResponse'
        - type: object
          title: 响应数据
          properties:
            data:
              allOf:
              - type: object
                title: 数据
                properties:
                  username:
                    title: 用户名
                    type: string
                  applicationId:
                    title: 应用标识
                    type: string
                  roles:
                    title: 角色数据
                    type: array
                    items:
                      $ref: '#/components/schemas/Role'


    ApplicationRolesAccountsResponse:
      allOf:
        - $ref: '#/components/schemas/DefaultApiResponse'
        - type: object
          title: 响应数据
          properties:
            data:
              allOf:
              - type: object
                title: 数据
                properties:
                  applicationId:
                    title: 应用标识
                    type: string
                  roleIds:
                    title: 角色IDs
                    type: array
                    items:
                      title: 角色ID
                      type: string
                  accounts:
                    title: 用户帐号数据
                    type: array
                    items:
                      title: 用户的帐号ID
                      type: string


    ApplicationRoleGroupsResponse:
      allOf:
        - $ref: '#/components/schemas/DefaultApiResponse'
        - type: object
          title: 响应数据
          properties:
            data:
              allOf:
              - type: object
                title: 数据
                properties:
                  applicationId:
                    title: 应用标识
                    type: string
                  rolecode:
                    title: 角色代码
                    type: string
                  groupIds:
                    title: 用户组ID列表
                    type: array
                    items:
                      title: 用户组ID
                      type: string
                  groups:
                    title: 用户组列表
                    type: array
                    items:
                      $ref: '#/components/schemas/GroupModel'