api.yaml

swagger: "2.0"
info:
  description: "This is the auth service for Muxi-X(Called 木犀内外)'s API document, please make sure you're using the python version server service."
  version: "2.0.0"
  title: "Auth Service v2"
  termsOfService: "http://muxixyz.com/api/auth"
  contact:
    email: "muxistudio@qq.com"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "pass.muxi-tech.xyz"
basePath: "/auth/api"
tags:
  - name: "auth"
    description: "auth API"
  - name: "oauth"
    description: "oauth2 API"
  - name: "profile"
    description: "profile API"
schemes:
  - "https"
  - "http"

paths:
  /signup:
    post:
      tags:
        - "auth"
      summary: "Signup a new account for Muxi-X."
      description: "Please make sure your email haven't signup."
      operationId: "user-signup"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "body"
          description: "Signup a user need username, email and passsword."
          required: true
          schema:
            $ref: "#/definitions/UserSignup"
      responses:
        200:
          description: "OK"
          schema:
            required:
              - id
            properties:
              id:
                type: "integer"
                format: "int64"
        401:
          description: "Username duplicated"
        402:
          description: "Email duplicated"
        403:
          description: "Bad Request"

  /signin:
    post:
      tags:
        - "auth"
      summary: "Login for Muxi-X."
      description: "Please make sure your username and password are right."
      operationId: "user-login"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "body"
          description: "Login need username(indeed username or email) and password base64."
          required: true
          schema:
            $ref: "#/definitions/UserLogin"
      responses:
        200:
          description: "OK"
          schema:
            required:
              - user_id
              - token
            properties:
              user_id:
                type: "integer"
                format: "int64"
              token:
                type: "string"
        400:
          description: "Password incorrect."
        401:
          description: "User not found or Bad Request."

  /check_name:
    get:
      tags:
        - "auth"
      summary: "Check the username is using or not."
      description: "Please make sure the query string you send include username."
      operationId: "check-username"
      produces:
        - "application/json"
      parameters:
        - name: "username"
          in: "query"
          description: "The username ready to check."
          required: true
          type: "string"
      responses:
        200:
          description: "Username nobody using."
        400:
          description: "Username someone using it."

  /check_email:
    get:
      tags:
        - "auth"
      summary: "Check the email is using or not."
      description: "Please make sure the query string you send include email."
      operationId: "check-email"
      produces:
        - "application/json"
      parameters:
        - name: "email"
          in: "query"
          description: "The email ready to check."
          required: true
          type: "string"
      responses:
        200:
          description: "Email nobody using."
        400:
          description: "Email someone using it."

  /check_token:
    get:
      tags:
        - "auth"
      summary: "Check the token and email is valid or not."
      description: "Please add the token and email to the query parameters"
      operationId: "check-token"
      produces:
        - "application/json"
      parameters:
        - name: "email"
          in: "query"
          description: "The email to check."
          required: true
          type: "string"
        - name: "token"
          in: "query"
          description: "The token to check"
          required: true
          type: "string"
      responses:
        200:
          description: "OK"
        400:
          description: "Bad Request"
        404:
          description: "User not found"
        500:
          description: "Internal error."

  /email:
    get:
      tags:
        - "auth"
      summary: "Get the email by username."
      description: "Please make sure the query string you send include username."
      operationId: "get-email"
      produces:
        - "application/json"
      parameters:
        - name: "username"
          in: "query"
          description: "The username for getting email."
          required: true
          type: "string"
      responses:
        200:
          description: "OK"
          schema:
            required:
              - email
            properties:
              email:
                type: "string"
                format: "email"
        404:
          description: "User not found."

  /password/get_captcha:
    post:
      tags:
        - "auth"
      summary: "Get captcha for reset password."
      description: "Please make sure your email address are right."
      operationId: "reset-getCaptcha"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "body"
          description: "Reset password need email address."
          required: true
          schema:
            $ref: "#/definitions/GetCaptcha"
      responses:
        200:
          description: "Captcha be sent."

  /password/check_captcha:
    post:
      tags:
        - "auth"
      summary: "Post captcha for reset password."
      description: "Please make sure your email address and captcha are right."
      operationId: "reset-postCaptcha"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "body"
          description: "Reset password need email address."
          required: true
          schema:
            $ref: "#/definitions/PostCaptcha"
      responses:
        200:
          description: "Captcha is OK."
        403:
          description: "Bad Request"
        404:
          description: "User not found."

  /password/reset:
    post:
      tags:
        - "auth"
      summary: "Reset the password."
      description: "Reset password need captcha, email address and new password."
      operationId: "reset-password"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "body"
          description: "Reset password need email address."
          required: true
          schema:
            $ref: "#/definitions/ResetPassword"
      responses:
        200:
          description: "Reset OK."
        403:
          description: "Bad Request"
        404:
          description: "User not found."
  /oauth:
    post:
      tags:
        - "oauth"
      summary: "login and get oauth code"
      parameters:
        - in: query
          name: response_type
          description: must be code
          required: true
          type: string
        - in: query
          name: client_id
          required: true
          type: string
        - in: query
          name: token_exp
          required: false
          type: string
          description: 过期时间（s）
        - in: body
          name: data
          schema:
            required:
              - username
              - password
            properties:
              username:
                type: string
              password:
                type: string
                description: base64
      responses:
        200:
          description: ok
          schema:
            type: object
            properties:
              code:
                type: string
              expired:
                type: integer

  /oauth/token:
    post:
      tags:
        - "oauth"
      summary: "get access token"
      consumes:
        - "multipart/form-data"
      produces:
        - "application/json"
      parameters:
        - in: query
          name: response_type
          description: must be token
          required: true
          type: string
        - in: query
          name: grant_type
          description: must be authorization_code
          required: true
          type: string
        - in: query
          name: client_id
          required: true
          type: string
        - in: formData
          name: client_secret
          required: true
          type: string
        - in: formData
          name: code
          required: true
          type: string
      responses:
        200:
          description: ok
          schema:
            $ref: "#/definitions/AccessToken"

  /oauth/token/refresh:
    post:
      tags:
        - "oauth"
      summary: "refresh access token"
      consumes:
        - "multipart/form-data"
      produces:
        - "application/json"
      parameters:
        - in: query
          name: grant_type
          description: must be refresh_token
          required: true
          type: string
        - in: query
          name: client_id
          required: true
          type: string
        - in: formData
          name: client_secret
          required: true
          type: string
        - in: formData
          name: refresh_token
          required: true
          type: string
      responses:
        200:
          description: ok
          schema:
            $ref: "#/definitions/AccessToken"

  /oauth/store:
    post:
      tags:
        - "oauth"
      summary: "register client with domain"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: body
          name: data
          schema:
            required:
              - domain
            properties:
              domain:
                type: string
      responses:
        200:
          description: ok
          schema:
            $ref: "#/definitions/ClientStore"

  /oauth/cas/callback:
    get:
      tags:
        - "oauth"
      summary: "handle CAS callback and redirect with oauth code"
      description: "This endpoint is used as the CAS service callback. The client should first redirect the browser to CAS login with a service URL that points to this endpoint and includes client_id, callback_url and optional token_exp. After CAS login succeeds, this service validates the CAS ticket, converts the CAS username into an independent OAuth subject in the form of cas:<username>, generates an OAuth authorization code, and finally redirects to callback_url with the code query parameter."
      parameters:
        - in: query
          name: ticket
          description: "CAS service ticket returned by CAS after successful login."
          required: true
          type: string
        - in: query
          name: client_id
          description: "OAuth client id that should receive the authorization code."
          required: true
          type: string
        - in: query
          name: callback_url
          description: "Business callback URL that will receive the generated OAuth authorization code."
          required: true
          type: string
        - in: query
          name: token_exp
          required: false
          description: "Optional access token expiry in seconds, passed through to the existing OAuth issuing logic."
          type: string
      responses:
        302:
          description: "Redirect to callback_url with the generated code query parameter."
        400:
          description: "Missing required callback parameters such as ticket, client_id or callback_url."
        401:
          description: "Invalid, expired or already-consumed CAS ticket."
        404:
          description: "Reserved for historical compatibility. The current implementation no longer maps CAS users back to the local users table."

  /user:
    get:
      tags:
        - "profile"
      summary: "get user info"
      parameters:
        - in: header
          name: token
          description: oauth2 access token
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/UserInfo"

definitions:
  UserSignup:
    type: "object"
    required:
      - "username"
      - "email"
      - "password"
    properties:
      username:
        type: "string"
      email:
        type: "string"
        format: "email"
        example: "muxistudio@qq.com"
      password:
        type: "string"
        format: "base64"
  UserLogin:
    type: "object"
    required:
      - "username"
      - "password"
    properties:
      username:
        type: "string"
        example: "muxistudio or muxistudio@qq.com"
      password:
        type: "string"
        format: "base64"
  GetCaptcha:
    type: "object"
    required:
      - "email"
    properties:
      email:
        type: "string"
        example: "email"
  PostCaptcha:
    type: "object"
    required:
      - "captcha"
      - "email"
    properties:
      captcha:
        type: "string"
      email:
        type: "string"
        format: "email"
        example: "muxistudio@qq.com"
  ResetPassword:
    type: "object"
    required:
      - "captcha"
      - "email"
      - "new_password"
    properties:
      captcha:
        type: "string"
      email:
        type: "string"
        format: "email"
        example: "muxistudio@qq.com"
      new_password:
        type: "string"
  AccessToken:
    type: "object"
    properties:
      access_token:
        type: string
      access_expired:
        type: integer
      refresh_token:
        type: string
      refresh_expired:
        type: integer
  ClientStore:
    type: "object"
    properties:
      client_id:
        type: string
      client_secret:
        type: string
  UserInfo:
    type: "object"
    properties:
      email:
        type: string
      birthday:
        type: string
      hometown:
        type: string
      group:
        type: string
      timejoin:
        type: string
      timeleft:
        type: string
      username:
        type: string
      role_id:
        type: integer
      left:
        type: boolean
      info:
        type: string
      avatar_url:
        type: string
      personal_blog:
        type: string
      github:
        type: string
      flickr:
        type: string
      weibo:
        type: string
      zhihu:
        type: string