Add kdoc

2023-12-03 16:27:51 +08:00
parent 95ea00e643
commit e16914967a
30 changed files with 802 additions and 117 deletions
--- a/src/main/kotlin/top/fatweb/api/controller/api/v1/AvatarController.kt
+++ b/src/main/kotlin/top/fatweb/api/controller/api/v1/AvatarController.kt
@@ -27,10 +27,21 @@ import top.fatweb.api.vo.api.v1.avatar.AvatarBase64Vo
 class AvatarController(
    private val avatarService: IAvatarService
 ) {
+    /**
+     * Get random avatar
+     *
+     * @param apiVersion Api version
+     * @param avatarBaseParam Avatar base parameters
+     * @return Avatar byte array
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see AvatarBaseParam
+     * @see ByteArray
+     */
    @Operation(summary = "获取随机头像")
    @GetMapping(produces = [MediaType.IMAGE_PNG_VALUE])
-    fun getDefault(@PathVariable apiVersion: String, @Valid avatarBaseParam: AvatarBaseParam?): ByteArray {
-        return when ((1..4).random()) {
+    fun getRandom(@PathVariable apiVersion: String, @Valid avatarBaseParam: AvatarBaseParam?): ByteArray =
+        when ((1..4).random()) {
            1 -> avatarService.triangle(avatarBaseParam)
            2 -> avatarService.square(avatarBaseParam)
            3 -> avatarService.identicon(avatarBaseParam)
@@ -43,15 +54,26 @@ class AvatarController(
                background = avatarBaseParam?.background
            })
        }
-    }

+    /**
+     * Get random avatar as base64
+     *
+     * @param apiVersion Api version
+     * @param avatarBaseParam Avatar base parameters
+     * @return Response object includes avatar base64 string
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see AvatarBaseParam
+     * @see ResponseResult
+     * @see AvatarBase64Vo
+     */
    @Operation(summary = "获取随机头像 Base64")
    @GetMapping("base64")
-    fun getDefaultBase64(
+    fun getRandomBase64(
        @PathVariable apiVersion: String,
        @Valid avatarBaseParam: AvatarBaseParam?
-    ): ResponseResult<AvatarBase64Vo> {
-        return ResponseResult.success(
+    ): ResponseResult<AvatarBase64Vo> =
+        ResponseResult.success(
            ResponseCode.API_AVATAR_SUCCESS, data = when ((1..4).random()) {
                1 -> avatarService.triangleBase64(avatarBaseParam)
                2 -> avatarService.squareBase64(avatarBaseParam)
@@ -66,65 +88,160 @@ class AvatarController(
                })
            }
        )
-    }

+    /**
+     * Get triangle avatar
+     *
+     * @param apiVersion Api version
+     * @param avatarBaseParam Avatar base parameters
+     * @return Avatar byte array
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see AvatarBaseParam
+     * @see ByteArray
+     */
    @Operation(summary = "三角形头像")
    @GetMapping("/triangle", produces = [MediaType.IMAGE_PNG_VALUE])
-    fun triangle(@PathVariable apiVersion: String, @Valid avatarBaseParam: AvatarBaseParam?): ByteArray {
-        return avatarService.triangle(avatarBaseParam)
-    }
+    fun triangle(@PathVariable apiVersion: String, @Valid avatarBaseParam: AvatarBaseParam?): ByteArray =
+        avatarService.triangle(avatarBaseParam)

+    /**
+     * Get triangle avatar as base64
+     *
+     * @param apiVersion Api version
+     * @param avatarBaseParam Avatar base parameters
+     * @return Response object includes avatar base64 string
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see AvatarBaseParam
+     * @see ResponseResult
+     * @see AvatarBase64Vo
+     */
    @Operation(summary = "三角形头像 Base64")
    @GetMapping("/triangle/base64")
-    fun triangleBase64(@PathVariable apiVersion: String, @Valid avatarBaseParam: AvatarBaseParam?): ResponseResult<AvatarBase64Vo> {
-        return ResponseResult.success(
+    fun triangleBase64(
+        @PathVariable apiVersion: String,
+        @Valid avatarBaseParam: AvatarBaseParam?
+    ): ResponseResult<AvatarBase64Vo> =
+        ResponseResult.success(
            ResponseCode.API_AVATAR_SUCCESS,
            data = avatarService.triangleBase64(avatarBaseParam)
        )
-    }

+    /**
+     * Get square avatar
+     *
+     * @param apiVersion Api version
+     * @param avatarBaseParam Avatar base parameters
+     * @return Avatar byte array
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see AvatarBaseParam
+     * @see ByteArray
+     */
    @Operation(summary = "正方形头像")
    @GetMapping("/square", produces = [MediaType.IMAGE_PNG_VALUE])
-    fun square(@PathVariable apiVersion: String, @Valid avatarBaseParam: AvatarBaseParam?): ByteArray {
-        return avatarService.square(avatarBaseParam)
-    }
+    fun square(@PathVariable apiVersion: String, @Valid avatarBaseParam: AvatarBaseParam?): ByteArray =
+        avatarService.square(avatarBaseParam)

+    /**
+     * Get square avatar as base64
+     *
+     * @param apiVersion Api version
+     * @param avatarBaseParam Avatar base parameters
+     * @return Response object includes avatar base64 string
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see AvatarBaseParam
+     * @see ResponseResult
+     * @see AvatarBase64Vo
+     */
    @Operation(summary = "正方形头像 Base64")
    @GetMapping("/square/base64")
-    fun squareBase64(@PathVariable apiVersion: String, @Valid avatarBaseParam: AvatarBaseParam?): ResponseResult<AvatarBase64Vo> {
-        return ResponseResult.success(
+    fun squareBase64(
+        @PathVariable apiVersion: String,
+        @Valid avatarBaseParam: AvatarBaseParam?
+    ): ResponseResult<AvatarBase64Vo> =
+        ResponseResult.success(
            ResponseCode.API_AVATAR_SUCCESS,
            data = avatarService.squareBase64(avatarBaseParam)
        )
-    }

+    /**
+     * Get identicon avatar
+     *
+     * @param apiVersion Api version
+     * @param avatarBaseParam Avatar base parameters
+     * @return Avatar byte array
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see AvatarBaseParam
+     * @see ByteArray
+     */
    @Operation(summary = "Identicon 头像")
    @GetMapping("/identicon", produces = [MediaType.IMAGE_PNG_VALUE])
-    fun identicon(@PathVariable apiVersion: String, @Valid avatarBaseParam: AvatarBaseParam?): ByteArray {
-        return avatarService.identicon(avatarBaseParam)
-    }
+    fun identicon(@PathVariable apiVersion: String, @Valid avatarBaseParam: AvatarBaseParam?): ByteArray =
+        avatarService.identicon(avatarBaseParam)

+    /**
+     * Get identicon avatar as base64
+     *
+     * @param apiVersion Api version
+     * @param avatarBaseParam Avatar base parameters
+     * @return Response object includes avatar base64 string
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see AvatarBaseParam
+     * @see ResponseResult
+     * @see AvatarBase64Vo
+     */
    @Operation(summary = "Identicon 头像 Base64")
    @GetMapping("/identicon/base64")
-    fun identiconBase64(@PathVariable apiVersion: String, @Valid avatarBaseParam: AvatarBaseParam?): ResponseResult<AvatarBase64Vo> {
-        return ResponseResult.success(
+    fun identiconBase64(
+        @PathVariable apiVersion: String,
+        @Valid avatarBaseParam: AvatarBaseParam?
+    ): ResponseResult<AvatarBase64Vo> =
+        ResponseResult.success(
            ResponseCode.API_AVATAR_SUCCESS,
            data = avatarService.identiconBase64(avatarBaseParam)
        )
-    }

+    /**
+     * Get GitHub avatar
+     *
+     * @param apiVersion Api version
+     * @param avatarGitHubParam Avatar base parameters
+     * @return Avatar byte array
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see AvatarGitHubParam
+     * @see ByteArray
+     */
    @Operation(summary = "GitHub 头像")
    @GetMapping("/github", produces = [MediaType.IMAGE_PNG_VALUE])
-    fun github(@PathVariable apiVersion: String, @Valid avatarGitHubParam: AvatarGitHubParam?): ByteArray {
-        return avatarService.github(avatarGitHubParam)
-    }
+    fun github(@PathVariable apiVersion: String, @Valid avatarGitHubParam: AvatarGitHubParam?): ByteArray =
+        avatarService.github(avatarGitHubParam)

+    /**
+     * Get GitHub avatar as base64
+     *
+     * @param apiVersion Api version
+     * @param avatarGitHubParam Avatar base parameters
+     * @return Response object includes avatar base64 string
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see AvatarGitHubParam
+     * @see ResponseResult
+     * @see AvatarBase64Vo
+     */
    @Operation(summary = "GitHub 头像 Base64")
    @GetMapping("/github/base64")
-    fun githubBase64(@PathVariable apiVersion: String, @Valid avatarGitHubParam: AvatarGitHubParam?): ResponseResult<AvatarBase64Vo> {
-        return ResponseResult.success(
+    fun githubBase64(
+        @PathVariable apiVersion: String,
+        @Valid avatarGitHubParam: AvatarGitHubParam?
+    ): ResponseResult<AvatarBase64Vo> =
+        ResponseResult.success(
            ResponseCode.API_AVATAR_SUCCESS,
            data = avatarService.githubBase64(avatarGitHubParam)
        )
-    }
 }
--- a/src/main/kotlin/top/fatweb/api/controller/permission/AuthenticationController.kt
+++ b/src/main/kotlin/top/fatweb/api/controller/permission/AuthenticationController.kt
@@ -14,6 +14,8 @@ import top.fatweb.api.entity.common.ResponseResult
 import top.fatweb.api.param.permission.LoginParam
 import top.fatweb.api.service.permission.IAuthenticationService
 import top.fatweb.api.util.WebUtil
+import top.fatweb.api.vo.permission.LoginVo
+import top.fatweb.api.vo.permission.TokenVo

 /**
 * Authentication controller
@@ -26,24 +28,59 @@ import top.fatweb.api.util.WebUtil
 class AuthenticationController(
    private val authenticationService: IAuthenticationService
 ) {
+    /**
+     * Login
+     *
+     * @param request
+     * @param loginParam Login parameters
+     * @return Response object includes login result
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see HttpServletRequest
+     * @see LoginParam
+     * @see ResponseResult
+     * @see LoginVo
+     */
    @Operation(summary = "登录")
    @PostMapping("/login")
-    fun login(request: HttpServletRequest, @Valid @RequestBody loginParam: LoginParam) = ResponseResult.success(
-        ResponseCode.PERMISSION_LOGIN_SUCCESS,
-        "Login success",
-        authenticationService.login(request, UserConverter.loginParamToUser(loginParam))
-    )
+    fun login(request: HttpServletRequest, @Valid @RequestBody loginParam: LoginParam): ResponseResult<LoginVo> =
+        ResponseResult.success(
+            ResponseCode.PERMISSION_LOGIN_SUCCESS,
+            "Login success",
+            authenticationService.login(request, UserConverter.loginParamToUser(loginParam))
+        )

+    /**
+     * Logout
+     *
+     * @param request
+     * @return Response object includes logout result
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see HttpServletRequest
+     * @see ResponseResult
+     */
    @Operation(summary = "登出")
    @PostMapping("/logout")
-    fun logout(request: HttpServletRequest) = when (authenticationService.logout(WebUtil.getToken(request))) {
+    fun logout(request: HttpServletRequest): ResponseResult<Nothing> = when (authenticationService.logout(WebUtil.getToken(request))) {
        true -> ResponseResult.success(ResponseCode.PERMISSION_LOGOUT_SUCCESS, "Logout success", null)
        false -> ResponseResult.fail(ResponseCode.PERMISSION_LOGOUT_FAILED, "Logout failed", null)
    }

+    /**
+     * Renew token
+     *
+     * @param request
+     * @return Response object includes new token
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see HttpServletRequest
+     * @see ResponseResult
+     * @see TokenVo
+     */
    @Operation(summary = "更新 Token")
    @GetMapping("/token")
-    fun renewToken(request: HttpServletRequest) = ResponseResult.success(
+    fun renewToken(request: HttpServletRequest): ResponseResult<TokenVo> = ResponseResult.success(
        ResponseCode.PERMISSION_TOKEN_RENEW_SUCCESS,
        "Token renew success",
        authenticationService.renewToken(WebUtil.getToken(request))
--- a/src/main/kotlin/top/fatweb/api/controller/permission/GroupController.kt
+++ b/src/main/kotlin/top/fatweb/api/controller/permission/GroupController.kt
@@ -10,8 +10,8 @@ import top.fatweb.api.entity.common.ResponseResult
 import top.fatweb.api.param.permission.group.*
 import top.fatweb.api.service.permission.IGroupService
 import top.fatweb.api.vo.PageVo
-import top.fatweb.api.vo.permission.base.GroupVo
 import top.fatweb.api.vo.permission.GroupWithRoleVo
+import top.fatweb.api.vo.permission.base.GroupVo

 /**
 * Group controller
@@ -25,67 +25,133 @@ import top.fatweb.api.vo.permission.GroupWithRoleVo
 class GroupController(
    val groupService: IGroupService
 ) {
+    /**
+     * Get group by ID
+     *
+     * @param id Group ID
+     * @return Response object includes group info
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see ResponseResult
+     * @see GroupWithRoleVo
+     */
    @Operation(summary = "获取单个用户组")
    @GetMapping("/{id}")
    @PreAuthorize("hasAnyAuthority('system:group:query:one')")
-    fun getOne(@PathVariable id: Long): ResponseResult<GroupWithRoleVo> {
-        return ResponseResult.databaseSuccess(
+    fun getOne(@PathVariable id: Long): ResponseResult<GroupWithRoleVo> =
+        ResponseResult.databaseSuccess(
            data = groupService.getOne(id)
        )
-    }

+    /**
+     * Get group paging information
+     *
+     * @param groupGetParam Get group parameters
+     * @return Response object includes group paging information
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see GroupGetParam
+     * @see ResponseResult
+     * @see PageVo
+     * @see GroupWithRoleVo
+     */
    @Operation(summary = "获取用户组")
    @GetMapping
    @PreAuthorize("hasAnyAuthority('system:group:query:all')")
-    fun get(@Valid groupGetParam: GroupGetParam?): ResponseResult<PageVo<GroupWithRoleVo>> {
-        return ResponseResult.databaseSuccess(
+    fun get(@Valid groupGetParam: GroupGetParam?): ResponseResult<PageVo<GroupWithRoleVo>> =
+        ResponseResult.databaseSuccess(
            data = groupService.getPage(groupGetParam)
        )
-    }

+    /**
+     * Get group list
+     *
+     * @return Response object includes group list
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see ResponseResult
+     * @see GroupVo
+     */
    @Operation(summary = "获取用户组列表")
    @GetMapping("/list")
    @PreAuthorize("hasAnyAuthority('system:group:query:list', 'system:user:add:one', 'system:user:modify:one')")
-    fun list(): ResponseResult<List<GroupVo>> {
-        return ResponseResult.databaseSuccess(
+    fun list(): ResponseResult<List<GroupVo>> =
+        ResponseResult.databaseSuccess(
            data = groupService.listAll()
        )
-    }

+    /**
+     * Add group
+     *
+     * @param groupAddParam Add group parameters
+     * @return Response object includes group information
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see GroupAddParam
+     * @see ResponseResult
+     * @see GroupVo
+     */
    @Operation(summary = "添加用户组")
    @PostMapping
    @PreAuthorize("hasAnyAuthority('system:group:add:one')")
-    fun add(@Valid @RequestBody groupAddParam: GroupAddParam): ResponseResult<GroupVo> {
-        return groupService.add(groupAddParam)?.let {
+    fun add(@Valid @RequestBody groupAddParam: GroupAddParam): ResponseResult<GroupVo> =
+        groupService.add(groupAddParam)?.let {
            ResponseResult.databaseSuccess(
                ResponseCode.DATABASE_INSERT_SUCCESS, data = it
            )
        } ?: let { ResponseResult.databaseFail(ResponseCode.DATABASE_INSERT_FAILED) }
-    }

+    /**
+     * Update group
+     *
+     * @param groupUpdateParam Update group parameters
+     * @return Response object includes group information
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see GroupUpdateParam
+     * @see ResponseResult
+     * @see GroupVo
+     */
    @Operation(summary = "修改用户组")
    @PutMapping
    @PreAuthorize("hasAnyAuthority('system:group:modify:one')")
-    fun update(@Valid @RequestBody groupUpdateParam: GroupUpdateParam): ResponseResult<GroupVo> {
-        return groupService.update(groupUpdateParam)?.let {
+    fun update(@Valid @RequestBody groupUpdateParam: GroupUpdateParam): ResponseResult<GroupVo> =
+        groupService.update(groupUpdateParam)?.let {
            ResponseResult.databaseSuccess(
                ResponseCode.DATABASE_UPDATE_SUCCESS, data = it
            )
        } ?: let { ResponseResult.databaseFail(ResponseCode.DATABASE_UPDATE_FILED) }
-    }

+    /**
+     * Update status of group
+     *
+     * @param groupUpdateStatusParam Update status of group parameters
+     * @return Response object
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see GroupUpdateStatusParam
+     * @see ResponseResult
+     */
    @Operation(summary = "修改用户组状态")
    @PatchMapping
    @PreAuthorize("hasAnyAuthority('system:group:modify:status')")
-    fun changStatus(@Valid @RequestBody groupChangeStatusParam: GroupChangeStatusParam): ResponseResult<Nothing> {
-        return if (groupService.changeStatus(groupChangeStatusParam)) {
+    fun updateStatus(@Valid @RequestBody groupUpdateStatusParam: GroupUpdateStatusParam): ResponseResult<Nothing> =
+        if (groupService.status(groupUpdateStatusParam)) {
            ResponseResult.databaseSuccess(ResponseCode.DATABASE_UPDATE_SUCCESS)
        } else {
            ResponseResult.databaseFail(ResponseCode.DATABASE_UPDATE_FILED)
        }
-    }

-    @Operation(summary = "删除角色")
+    /**
+     * Delete group by ID
+     *
+     * @param id Group ID
+     * @return Response object
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see ResponseResult
+     */
+    @Operation(summary = "删除用户组")
    @DeleteMapping("/{id}")
    @PreAuthorize("hasAnyAuthority('system:group:delete:one')")
    fun delete(@PathVariable id: Long): ResponseResult<Nothing> {
@@ -93,7 +159,17 @@ class GroupController(
        return ResponseResult.databaseSuccess(ResponseCode.DATABASE_DELETE_SUCCESS)
    }

-    @Operation(summary = "批量删除角色")
+    /**
+     * Delete group by list
+     *
+     * @param groupDeleteParam Delete group parameters
+     * @return Response object
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see GroupDeleteParam
+     * @see ResponseResult
+     */
+    @Operation(summary = "批量删除用户组")
    @DeleteMapping
    @PreAuthorize("hasAnyAuthority('system:group:delete:multiple')")
    fun deleteList(@Valid @RequestBody groupDeleteParam: GroupDeleteParam): ResponseResult<Nothing> {
--- a/src/main/kotlin/top/fatweb/api/controller/permission/PowerController.kt
+++ b/src/main/kotlin/top/fatweb/api/controller/permission/PowerController.kt
@@ -8,6 +8,7 @@ import org.springframework.web.bind.annotation.RequestMapping
 import org.springframework.web.bind.annotation.RestController
 import top.fatweb.api.entity.common.ResponseResult
 import top.fatweb.api.service.permission.IPowerService
+import top.fatweb.api.vo.permission.PowerSetVo

 /**
 * Power controller
@@ -21,8 +22,16 @@ import top.fatweb.api.service.permission.IPowerService
 class PowerController(
    private val powerService: IPowerService
 ) {
+    /**
+     * Get power list
+     *
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see ResponseResult
+     * @see PowerSetVo
+     */
    @Operation(summary = "获取权限列表")
    @GetMapping("/list")
    @PreAuthorize("hasAnyAuthority('system:power:query:list', 'system:role:add:one', 'system:role:modify:one')")
-    fun getList() = ResponseResult.databaseSuccess(data = powerService.getList())
+    fun getList(): ResponseResult<PowerSetVo> = ResponseResult.databaseSuccess(data = powerService.getList())
 }
--- a/src/main/kotlin/top/fatweb/api/controller/permission/RoleController.kt
+++ b/src/main/kotlin/top/fatweb/api/controller/permission/RoleController.kt
@@ -25,6 +25,16 @@ import top.fatweb.api.vo.permission.base.RoleVo
 class RoleController(
    private val roleService: IRoleService
 ) {
+    /**
+     * Get role by ID
+     *
+     * @param id Role ID
+     * @return Response object includes role information
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see ResponseResult
+     * @see RoleWithPowerVo
+     */
    @Operation(summary = "获取单个角色")
    @GetMapping("/{id}")
    @PreAuthorize("hasAnyAuthority('system:role:query:one')")
@@ -34,6 +44,17 @@ class RoleController(
        )
    }

+    /**
+     * Get role paging information
+     *
+     * @param roleGetParam Get role parameters
+     * @return Response object includes role paging information
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see RoleGetParam
+     * @see ResponseResult
+     * @see RoleWithPowerVo
+     */
    @Operation(summary = "获取角色")
    @GetMapping
    @PreAuthorize("hasAnyAuthority('system:role:query:all')")
@@ -43,6 +64,15 @@ class RoleController(
        )
    }

+    /**
+     * Get role list
+     *
+     * @return Response object includes role list
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see ResponseResult
+     * @see RoleVo
+     */
    @Operation(summary = "获取角色列表")
    @GetMapping("/list")
    @PreAuthorize("hasAnyAuthority('system:role:query:list', 'system:group:add:one', 'system:group:modify:one', 'system:user:add:one', 'system:user:modify:one')")
@@ -52,6 +82,17 @@ class RoleController(
        )
    }

+    /**
+     * Add role
+     *
+     * @param roleAddParam Add role parameters
+     * @return Response object includes role information
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see RoleAddParam
+     * @see ResponseResult
+     * @see RoleVo
+     */
    @Operation(summary = "添加角色")
    @PostMapping
    @PreAuthorize("hasAnyAuthority('system:role:add:one')")
@@ -63,6 +104,17 @@ class RoleController(
        } ?: let { ResponseResult.databaseFail(ResponseCode.DATABASE_INSERT_FAILED) }
    }

+    /**
+     * Update role
+     *
+     * @param roleUpdateParam Update role parameters
+     * @return Response object includes role information
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see RoleUpdateParam
+     * @see ResponseResult
+     * @see RoleVo
+     */
    @Operation(summary = "修改角色")
    @PutMapping
    @PreAuthorize("hasAnyAuthority('system:role:modify:one')")
@@ -74,17 +126,36 @@ class RoleController(
        } ?: let { ResponseResult.databaseFail(ResponseCode.DATABASE_UPDATE_FILED) }
    }

+    /**
+     * Update status of role
+     *
+     * @param roleUpdateStatusParam Update status of role parameters
+     * @return Response object
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see RoleUpdateStatusParam
+     * @see ResponseResult
+     */
    @Operation(summary = "修改角色状态")
    @PatchMapping
    @PreAuthorize("hasAnyAuthority('system:role:modify:status')")
-    fun changStatus(@Valid @RequestBody roleChangeStatusParam: RoleChangeStatusParam): ResponseResult<Nothing> {
-        return if (roleService.changeStatus(roleChangeStatusParam)) {
+    fun status(@Valid @RequestBody roleUpdateStatusParam: RoleUpdateStatusParam): ResponseResult<Nothing> {
+        return if (roleService.status(roleUpdateStatusParam)) {
            ResponseResult.databaseSuccess(ResponseCode.DATABASE_UPDATE_SUCCESS)
        } else {
            ResponseResult.databaseFail(ResponseCode.DATABASE_UPDATE_FILED)
        }
    }

+    /**
+     * Delete role by ID
+     *
+     * @param id
+     * @return Response object
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see ResponseResult
+     */
    @Operation(summary = "删除角色")
    @DeleteMapping("/{id}")
    @PreAuthorize("hasAnyAuthority('system:role:delete:one')")
@@ -93,6 +164,16 @@ class RoleController(
        return ResponseResult.databaseSuccess(ResponseCode.DATABASE_DELETE_SUCCESS)
    }

+    /**
+     * Delete role by list
+     *
+     * @param roleDeleteParam Delete role parameters
+     * @return Response object
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see RoleDeleteParam
+     * @see ResponseResult
+     */
    @Operation(summary = "批量删除角色")
    @DeleteMapping
    @PreAuthorize("hasAnyAuthority('system:role:delete:multiple')")
--- a/src/main/kotlin/top/fatweb/api/controller/permission/UserController.kt
+++ b/src/main/kotlin/top/fatweb/api/controller/permission/UserController.kt
@@ -27,64 +27,130 @@ import top.fatweb.api.vo.permission.UserWithRoleInfoVo
 class UserController(
    private val userService: IUserService
 ) {
+    /**
+     * Get current user information
+     *
+     * @return Response object includes user information
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see ResponseResult
+     * @see UserWithPowerInfoVo
+     */
    @Operation(summary = "获取当前用户信息")
    @GetMapping("info")
-    fun getInfo(): ResponseResult<UserWithPowerInfoVo> {
+    fun getInfo(): ResponseResult<UserWithPowerInfoVo> =
        userService.getInfo()?.let {
-            return ResponseResult.databaseSuccess(data = it)
-        } ?: let { return ResponseResult.databaseFail() }
-    }
+            ResponseResult.databaseSuccess(data = it)
+        } ?: let { ResponseResult.databaseFail() }

+    /**
+     * Get user by ID
+     *
+     * @param id User ID
+     * @return Response object includes user information
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see ResponseResult
+     * @see UserWithRoleInfoVo
+     */
    @Operation(summary = "获取单个用户")
    @GetMapping("/{id}")
    @PreAuthorize("hasAnyAuthority('system:user:query:one')")
-    fun getOne(@PathVariable id: Long): ResponseResult<UserWithRoleInfoVo> {
-        return userService.getOne(id)?.let {
+    fun getOne(@PathVariable id: Long): ResponseResult<UserWithRoleInfoVo> =
+        userService.getOne(id)?.let {
            ResponseResult.databaseSuccess(data = it)
        } ?: let {
            throw NoRecordFoundException()
        }
-    }

+    /**
+     * Get user paging information
+     *
+     * @param userGetParam Get user parameters
+     * @return Response object includes user paging information
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see UserGetParam
+     * @see ResponseResult
+     * @see UserWithRoleInfoVo
+     */
    @Operation(summary = "获取用户")
    @GetMapping
    @PreAuthorize("hasAnyAuthority('system:user:query:all')")
-    fun get(@Valid userGetParam: UserGetParam?): ResponseResult<PageVo<UserWithRoleInfoVo>> {
-        return ResponseResult.databaseSuccess(
+    fun get(@Valid userGetParam: UserGetParam?): ResponseResult<PageVo<UserWithRoleInfoVo>> =
+        ResponseResult.databaseSuccess(
            data = userService.getPage(userGetParam)
        )
-    }

+    /**
+     * Add user
+     *
+     * @param userAddParam Add user parameters
+     * @return Response object includes user information
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see UserAddParam
+     * @see ResponseResult
+     * @see UserWithPasswordRoleInfoVo
+     */
    @Operation(summary = "添加用户")
    @PostMapping
    @PreAuthorize("hasAnyAuthority('system:user:add:one')")
-    fun add(@Valid @RequestBody userAddParam: UserAddParam): ResponseResult<UserWithPasswordRoleInfoVo> {
-        return userService.add(userAddParam)?.let {
+    fun add(@Valid @RequestBody userAddParam: UserAddParam): ResponseResult<UserWithPasswordRoleInfoVo> =
+        userService.add(userAddParam)?.let {
            ResponseResult.databaseSuccess(
                ResponseCode.DATABASE_INSERT_SUCCESS, data = it
            )
        } ?: let { ResponseResult.databaseFail(ResponseCode.DATABASE_INSERT_FAILED) }
-    }

+    /**
+     * Update user
+     *
+     * @param userUpdateParam Update user parameters
+     * @return Response object includes user information
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see UserUpdateParam
+     * @see ResponseResult
+     * @see UserWithRoleInfoVo
+     */
    @Operation(summary = "修改用户")
    @PutMapping
    @PreAuthorize("hasAnyAuthority('system:user:modify:one')")
-    fun update(@Valid @RequestBody userUpdateParam: UserUpdateParam): ResponseResult<UserWithRoleInfoVo> {
-        return userService.update(userUpdateParam)?.let {
+    fun update(@Valid @RequestBody userUpdateParam: UserUpdateParam): ResponseResult<UserWithRoleInfoVo> =
+        userService.update(userUpdateParam)?.let {
            ResponseResult.databaseSuccess(
                ResponseCode.DATABASE_UPDATE_SUCCESS, data = it
            )
        } ?: let { ResponseResult.databaseFail(ResponseCode.DATABASE_UPDATE_FILED) }
-    }

+    /**
+     * Update user password
+     *
+     * @param userUpdatePasswordParam Update user password parameters
+     * @return Response object
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see UserUpdatePasswordParam
+     * @see ResponseResult
+     */
    @Operation(summary = "修改密码")
    @PatchMapping
    @PreAuthorize("hasAnyAuthority('system:user:modify:password')")
-    fun changePassword(@Valid @RequestBody userChangePasswordParam: UserChangePasswordParam): ResponseResult<Nothing> {
-        userService.changePassword(userChangePasswordParam)
+    fun password(@Valid @RequestBody userUpdatePasswordParam: UserUpdatePasswordParam): ResponseResult<Nothing> {
+        userService.password(userUpdatePasswordParam)
        return ResponseResult.databaseSuccess(ResponseCode.DATABASE_UPDATE_SUCCESS)
    }

+    /**
+     * Delete user by ID
+     *
+     * @param id User ID
+     * @return Response object
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see ResponseResult
+     */
    @Operation(summary = "删除用户")
    @DeleteMapping("/{id}")
    @PreAuthorize("hasAnyAuthority('system:user:delete:one')")
@@ -93,6 +159,16 @@ class UserController(
        return ResponseResult.databaseSuccess(ResponseCode.DATABASE_DELETE_SUCCESS)
    }

+    /**
+     * Delete user by list
+     *
+     * @param userDeleteParam Delete user parameters
+     * @return Response object
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see UserDeleteParam
+     * @see ResponseResult
+     */
    @Operation(summary = "批量删除用户")
    @DeleteMapping
    @PreAuthorize("hasAnyAuthority('system:user:delete:multiple')")
@@ -100,5 +176,4 @@ class UserController(
        userService.delete(userDeleteParam)
        return ResponseResult.databaseSuccess(ResponseCode.DATABASE_DELETE_SUCCESS)
    }
-}
-
+}
--- a/src/main/kotlin/top/fatweb/api/controller/system/SysLogController.kt
+++ b/src/main/kotlin/top/fatweb/api/controller/system/SysLogController.kt
@@ -27,6 +27,17 @@ import top.fatweb.api.vo.system.SysLogVo
 class SysLogController(
    private val sysLogService: ISysLogService
 ) {
+    /**
+     * Get system log
+     *
+     * @param sysLogGetParam Get system log parameters
+     * @return Response object includes system log
+     * @author FatttSnake, fatttsnake@gmail.com
+     * @since 1.0.0
+     * @see SysLogGetParam
+     * @see ResponseResult
+     * @see SysLogVo
+     */
    @Operation(summary = "获取")
    @GetMapping
    @PreAuthorize("hasAnyAuthority('system:log:query:all')")