swagger: "2.0"
info:
  version: "0.0.1"
  title: 单点登陆数据api接口
# during dev, should point to your local machine
host: employee.cathay-ins.com.cn
# basePath prefixes all resource paths
basePath: /
#
schemes:
  # tip: remove http to make production-grade
  - http
  - https
# format of bodies a client can send (Content-Type)
consumes:
  - application/json
# format of the responses to the client (Accepts)
produces:
  - application/json
tags:
- name: service
  description: 业务应用JAR包请求员工中心相关的鉴权、验证token接口
- name: browser
  description: 浏览器向业务应用请求RESTFUL数据时，被SSO过滤器拦截处理的几种情况
paths:
  /api/sso/dd/verifyAuthCode/{tmpAuthCode}:
    post:
      tags:
      - service
      description: 验证钉钉tmpAuthCode的合法性
      parameters:
      - name: tmpAuthCode
        description: 钉钉tmpAuthCode，用户扫码确认后生成
        in: path
        type: string
        required: true
      responses:
        200:
          description: 成功
          schema:
            $ref: '#/definitions/AuthSuccess'
        401:
          description: Error
          schema:
            $ref: "#/definitions/Error401"
  /api/sso/user/verifyUsernameAndPassword:
    post:
      tags:
      - service
      description: 验证登录账号和密码的合法性
      parameters:
      - name: json
        description: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/LoginObject'
      responses:
        200:
          description: 成功
          schema:
            $ref: '#/definitions/AuthSuccess'
        401:
          description: Error
          schema:
            $ref: "#/definitions/Error401"
            
  /api/sso/caToken:
    get:
      description: 从cookie中获取caToken并展示对应用户信息
      tags:
      - browser
      responses:
        200:
          description: 返回数据成功
          schema:
            $ref: "schema/user.yaml#/definitions/User"
        400:
          description: 返回数据失败
          schema:
            $ref: "#/definitions/Error401"
            
  /api/sso/caToken/{caToken}:
    put:
      description: 更新caToken心跳时间，更新成功，返回AuthSucces对象；如果caToken失效，返回401无权限
      tags:
      - service
      parameters:
      - name: caToken
        description: cathayAuthToken
        in: path
        type: string
        required: true
      responses:
        200:
          description: 返回数据成功
          # responses may fall through to errors
          schema:
            $ref: '#/definitions/AuthSuccess'
        401:
          description: Error
          schema:
            $ref: "#/definitions/Error401"
    delete:
      description: 删除caToken，用于登出操作
      tags:
      - service
      parameters:
      - name: caToken
        description: cathayAuthToken
        in: path
        type: string
        required: true
      responses:
        200:
          description: 返回数据成功
          # responses may fall through to errors
          schema:
            type: string
            default: ok
        401:
          description: Error
          schema:
            $ref: "#/definitions/Error401"

  /PATH_FROM_BROWSER_TO_FETCH_DATA/CASE_OF_LOGIN:
    get:
      tags:
      - browser
      description: 模拟已经登陆HTTP REQUEST
      parameters:
      - name: Cookie[caToken]
        in: header
        required: true
        type: string
      responses:
        200:
          description: 返回本身业务数据
 
            
  /PATH_FROM_BROWSER_TO_FETCH_DATA/CASE_OF_UNLOGIN:
    get:
      tags:
      - browser
      description: 模拟未登录时的HTTP REQUEST, 无token
      responses:
        401:
          description: 返回无权限, [unlogin, timeout]两种
          schema:
            $ref: "#/definitions/Error401"
            
  /PATH_FROM_BROWSER_TO_FETCH_DATA/CASE_OF_TIMEOUT:
    get:
      tags:
      - browser
      description: 模拟session超时的HTTP REQUEST
      parameters:
      - name: Cookie[caToken]
        in: header
        required: true
        type: string
      responses:
        401:
          description: 返回无权限, [unlogin, timeout]两种
          schema:
            $ref: "#/definitions/Error401"
            
  /PATH_FROM_BROWSER_TO_FETCH_DATA/CASE_OF_LOGIN_BY_SCAN_DD:
    get:
      tags:
      - browser
      description: 模拟钉钉扫码登陆鉴权
      parameters:
      - name: CATHAY_AUTH_TYPE
        description: 此处case为"ddScan"
        in: header
        required: true
        type: string
        default: ddScan
        enum:
        - password
        - ddScan
      - name: CATHAY_AUTH_DD_TMP_CODE
        in: header
        required: true
        type: string
      responses:
        200:
          description: 除了返回本身业务数据外，还需返回token信息
          headers:
            SetCookie: 
              description: 通过cookie设置token, example->caToken=1233456
              type: string
          schema:
            type: object
            description: 业务本身的数据
        401:
          description: 账号或密码错误
          schema:
            $ref: "#/definitions/Error401"
            
            
  /PATH_FROM_BROWSER_TO_FETCH_DATA/CASE_OF_LOGIN_BY_PASSWORD:
    get:
      tags:
      - browser
      description: 账号密码登陆鉴权
      parameters:
      - name: CATHAY_AUTH_TYPE
        description: 此处值为"password"
        in: header
        required: true
        type: string
        default: password
        enum:
        - password
        - ddScan
      - name: CATHAY_AUTH_USERNAME
        in: header
        required: true
        type: string
      - name: CATHAY_AUTH_PASSWORD
        in: header
        required: true
        type: string
      responses:
        200:
          description: 除了返回本身业务数据外，还需返回token信息
          headers:
            SetCookie: 
              description: 通过cookie设置token, example->caToken=1233456
              type: string
          schema:
            type: object
            description: 业务本身的数据
        401:
          description: 账号或密码错误
          schema:
            $ref: "#/definitions/Error401"
              

# complex objects have schema definitions
definitions:
  AuthSuccess:
    type: object
    properties:
      caToken:
        type: string
        description: 验证成功后返回的token
      userInfo:
        $ref: "schema/user.yaml#/definitions/User"
  LoginObject:
    required:
      - username
      - password
    properties:
      username:
        type: string
        description: 账号，可以是邮箱，手机号码或者工号
      password:
        type: string
        description: 密码
  Error401:
    required:
      - code
      - message
    properties:
      code:
        type: string
        description: 业务出错码，请参见 http://wiki.cathay-inc.com:8090/pages/viewpage.action?pageId=68927
      message:
        type: string