juwan-backend/desc/api/users.api

syntax = "v1"

info(
    author: "Asadz"
    date: "2024-06-19"
    version: "1.0"
)

type (
    EmptyResp {
    }
    SearchUserResp {
        Username string `json:"username"`
        UserId int64 `json:"userId"`
        Nickname string `json:"nickname"`
        Avatar string `json:"avatar"`
        Bio string `json:"bio"`
        Page int64 `json:"page"`
        Limit int64 `json:"limit"`
    }
    ResetPasswordByVcode {
        Email string `json:"email"`
        Password string `json:"password"`
        Vcode string `json:"vcode"`
    }
    RegisterReq {
        Username string `json:"username" binding:"required,min=3,max=50"`
        Password string `json:"password" binding:"required,min=6,max=128"`
        Email string `json:"email,omitempty" binding:"omitempty,email"`
        Phone string `json:"phone,omitempty" binding:"omitempty,len=11"`
        Vcode int32 `json:"vcode"`
    }
    RegisterResp {
        UserId int64 `json:"userId"`
        Username string `json:"username"`
        Email string `json:"email"`
        Message string `json:"message"`
    }
    LoginReq {
        Username string `json:"username" binding:"required"`
        Password string `json:"password" binding:"required"`
    }
    LoginResp {
        UserId int64 `json:"userId"`
        Username string `json:"username"`
        Email string `json:"email"`
        Token string `json:"token"`
        Expires int64 `json:"expires"`
    }
    GetUserInfoReq {
        UserId int64 `path:"userId" binding:"required,gt=0"`
    }
    UserInfo {
        UserId int64 `json:"userId"`
        Username string `json:"username"`
        Email string `json:"email"`
        Phone string `json:"phone"`
        Avatar string `json:"avatar"`
        Status int `json:"status"`
        CreateAt int64 `json:"createAt"`
        UpdateAt int64 `json:"updateAt"`
    }
    UpdateUserInfoReq {
        Nickname *string `json:"nickname,omitempty"`
        Avatar *string `json:"avatar,omitempty"`
        Bio *string `json:"bio,omitempty"`
    }
    UpdateUserInfoResp {
        UserId int64 `json:"userId"`
        Message string `json:"message"`
    }
    UpdatePasswordReq {
        UserId int64 `path:"userId" binding:"required,gt=0"`
        OldPassword string `json:"oldPassword" binding:"required"`
        NewPassword string `json:"newPassword" binding:"required,min=6,max=128"`
    }
    UpdatePasswordResp {
        Message string `json:"message"`
    }
    LogoutReq {
        UserId int64 `path:"userId" binding:"required,gt=0"`
        Token string `header:"Authorization" binding:"required"`
    }
    LogoutResp {
        Message string `json:"message"`
    }
    ErrorResp {
        Code int `json:"code"`
        Message string `json:"message"`
    }
)

@server(
    group: user
    prefix:     /api/v1/auth
    middleware: Logger
)
service user-api {
    @doc(
        summary: "用户注册接口"
        description: "通过用户名、密码、邮箱、电话号码注册新用户账户"
    )
    @handler Register
    post /register (RegisterReq) returns (RegisterResp)

    @doc(
        summary: "用户登录接口"
        description: "使用用户名和密码进行登录，返回访问令牌和用户信息"
    )
    @handler Login
    post /login (LoginReq) returns (LoginResp)

    @doc(
        summary: "修改用户密码"
        description: "验证旧密码后修改为新密码，需要提供原密码"
    )
    @handler UpdatePassword
    put /:userId/password (UpdatePasswordReq) returns (UpdatePasswordResp)

    @doc(
        summary: "用户登出"
        description: "需要携带 Authorization 令牌，清除用户会话并使令牌失效"
    )
    @handler Logout
    post /:userId/logout (LogoutReq) returns (LogoutResp)

    @doc "修改密码-使用验证码"
    @handler UpdatePasswordByVcode
    put /forgot-password/reset (ResetPasswordByVcode) returns (EmptyResp)
}

@server(
    group: user
    prefix:     /api/v1/user
    middleware: Logger
)
service user-api {
    @doc "获取当前登录用户信息"
    @handler GetMe
    get /me returns (UserInfo)

    @doc "通过用户名搜索用户"
    @handler SearchUsersByUsername
    get /search () returns ([]UserInfo)

    @doc "更改当前登录用户信息"
    @handler UpdateMe
    put /me (UpdateUserInfoReq) returns (UserInfo)

    @doc(
        summary: "获取用户信息"
        description: "根据用户ID获取用户的详细信息，包含个人资料和账户状态"
    )
    @handler GetUserInfo
    get /:userId (GetUserInfoReq) returns (UserInfo)

    @doc(
        summary: "修改用户信息"
        description: "修改用户的邮箱、电话号码、头像等信息"
    )
    @handler UpdateUserInfo
    put /:userId (UpdateUserInfoReq) returns (UpdateUserInfoResp)
}