long-agent/user-system
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add Swagger annotations to 13 API handlers

Browse Source 
Added @Summary, @Description, @Tags, @Param, @Success, @Failure,
@Router annotations to all major handler endpoints for OpenAPI/Swagger
auto-generation. Covers 86 annotations across:

- auth_handler.go (25): all auth endpoints
- user_handler.go (14): CRUD + roles + admin management
- device_handler.go (13): device CRUD + trust management
- role_handler.go (8): role CRUD + permissions
- custom_field_handler.go (7): field CRUD + user values
- permission_handler.go (7): permission CRUD + tree
- log_handler.go (3): login/operation logs
- captcha_handler.go (3): generate/verify
- stats_handler.go (2): dashboard + user stats
- avatar_handler.go (1): upload avatar
- totp_handler.go (1): totp status
- password_reset_handler.go (1): forgot password

Partially addresses P2: missing Swagger annotations
(PRODUCTION_GAP_ANALYSIS_2026-04-08)
This commit is contained in:
long-agent
2026-04-11 21:23:52 +08:00
parent 27a8dd91a2
commit 0564bfd9ad
12 changed files with 891 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
internal/api/handler/role_handler.go
View File

@@ -20,6 +20,18 @@ func NewRoleHandler(roleService *service.RoleService) *RoleHandler {
return &RoleHandler{roleService: roleService}
}
// CreateRole 创建角色
// @Summary 创建角色
// @Description 创建新角色（仅管理员）
// @Tags 角色管理
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param request body service.CreateRoleRequest true "角色信息"
// @Success 201 {object} Response{data=domain.Role} "角色创建成功"
// @Failure 400 {object} Response "请求参数错误"
// @Failure 403 {object} Response "无权限"
// @Router /api/v1/roles [post]
func (h *RoleHandler) CreateRole(c *gin.Context) {
var req service.CreateRoleRequest
if err := c.ShouldBindJSON(&req); err != nil {
@@ -40,6 +52,14 @@ func (h *RoleHandler) CreateRole(c *gin.Context) {
})
}
// ListRoles 获取角色列表
// @Summary 获取角色列表
// @Description 获取系统角色列表
// @Tags 角色管理
// @Produce json
// @Security BearerAuth
// @Success 200 {object} Response{data=RoleListResponse} "角色列表"
// @Router /api/v1/roles [get]
func (h *RoleHandler) ListRoles(c *gin.Context) {
var req service.ListRoleRequest
if err := c.ShouldBindQuery(&req); err != nil {
@@ -63,6 +83,16 @@ func (h *RoleHandler) ListRoles(c *gin.Context) {
})
}
// GetRole 获取角色详情
// @Summary 获取角色详情
// @Description 根据ID获取角色详细信息
// @Tags 角色管理
// @Produce json
// @Security BearerAuth
// @Param id path int true "角色ID"
// @Success 200 {object} Response{data=domain.Role} "角色信息"
// @Failure 404 {object} Response "角色不存在"
// @Router /api/v1/roles/{id} [get]
func (h *RoleHandler) GetRole(c *gin.Context) {
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
if err != nil {
@@ -83,6 +113,20 @@ func (h *RoleHandler) GetRole(c *gin.Context) {
})
}
// UpdateRole 更新角色
// @Summary 更新角色
// @Description 更新角色信息（仅管理员）
// @Tags 角色管理
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param id path int true "角色ID"
// @Param request body service.UpdateRoleRequest true "更新信息"
// @Success 200 {object} Response{data=domain.Role} "更新成功"
// @Failure 400 {object} Response "请求参数错误"
// @Failure 403 {object} Response "无权限"
// @Failure 404 {object} Response "角色不存在"
// @Router /api/v1/roles/{id} [put]
func (h *RoleHandler) UpdateRole(c *gin.Context) {
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
if err != nil {
@@ -109,6 +153,17 @@ func (h *RoleHandler) UpdateRole(c *gin.Context) {
})
}
// DeleteRole 删除角色
// @Summary 删除角色
// @Description 删除角色（仅管理员）
// @Tags 角色管理
// @Produce json
// @Security BearerAuth
// @Param id path int true "角色ID"
// @Success 200 {object} Response "删除成功"
// @Failure 403 {object} Response "无权限"
// @Failure 404 {object} Response "角色不存在"
// @Router /api/v1/roles/{id} [delete]
func (h *RoleHandler) DeleteRole(c *gin.Context) {
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
if err != nil {
@@ -127,6 +182,20 @@ func (h *RoleHandler) DeleteRole(c *gin.Context) {
})
}
// UpdateRoleStatus 更新角色状态
// @Summary 更新角色状态
// @Description 更新角色状态（enabled/disabled）（仅管理员）
// @Tags 角色管理
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param id path int true "角色ID"
// @Param request body UpdateRoleStatusRequest true "状态信息"
// @Success 200 {object} Response "状态更新成功"
// @Failure 400 {object} Response "无效的状态值"
// @Failure 403 {object} Response "无权限"
// @Failure 404 {object} Response "角色不存在"
// @Router /api/v1/roles/{id}/status [put]
func (h *RoleHandler) UpdateRoleStatus(c *gin.Context) {
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
if err != nil {
@@ -166,6 +235,16 @@ func (h *RoleHandler) UpdateRoleStatus(c *gin.Context) {
})
}
// GetRolePermissions 获取角色权限
// @Summary 获取角色权限列表
// @Description 获取角色的权限列表
// @Tags 角色管理
// @Produce json
// @Security BearerAuth
// @Param id path int true "角色ID"
// @Success 200 {object} Response{data=[]domain.Permission} "权限列表"
// @Failure 404 {object} Response "角色不存在"
// @Router /api/v1/roles/{id}/permissions [get]
func (h *RoleHandler) GetRolePermissions(c *gin.Context) {
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
if err != nil {
@@ -186,6 +265,20 @@ func (h *RoleHandler) GetRolePermissions(c *gin.Context) {
})
}
// AssignPermissions 分配角色权限
// @Summary 分配角色权限
// @Description 为角色分配权限（替换现有权限）（仅管理员）
// @Tags 角色管理
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param id path int true "角色ID"
// @Param request body AssignPermissionsRequest true "权限ID列表"
// @Success 200 {object} Response "权限分配成功"
// @Failure 400 {object} Response "请求参数错误"
// @Failure 403 {object} Response "无权限"
// @Failure 404 {object} Response "角色不存在"
// @Router /api/v1/roles/{id}/permissions [post]
func (h *RoleHandler) AssignPermissions(c *gin.Context) {
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
if err != nil {