docs: add Swagger annotations to 5 handlers

Add comprehensive Swagger/Swagger comments to:
- export_handler.go (ExportUsers, ImportUsers, GetImportTemplate)
- sms_handler.go (SendCode, LoginByCode)
- sso_handler.go (Authorize, Token, Introspect, Revoke, UserInfo)
- theme_handler.go (8 endpoints)
- webhook_handler.go (5 endpoints)

All 18 handlers now have Swagger annotations.
This commit is contained in:
2026-04-11 22:49:13 +08:00
parent 1929c42e35
commit 84d9ed28af
5 changed files with 296 additions and 20 deletions

View File

@@ -19,6 +19,19 @@ func NewWebhookHandler(webhookService *service.WebhookService) *WebhookHandler {
return &WebhookHandler{webhookService: webhookService}
}
// CreateWebhook 创建 Webhook
// @Summary 创建 Webhook
// @Description 创建新的 Webhook 配置
// @Tags Webhook管理
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param request body service.CreateWebhookRequest true "Webhook信息"
// @Success 201 {object} Response{data=domain.Webhook} "Webhook创建成功"
// @Failure 400 {object} Response "请求参数错误"
// @Failure 401 {object} Response "未认证"
// @Failure 500 {object} Response "服务器错误"
// @Router /api/v1/webhooks [post]
func (h *WebhookHandler) CreateWebhook(c *gin.Context) {
var req service.CreateWebhookRequest
if err := c.ShouldBindJSON(&req); err != nil {
@@ -38,6 +51,19 @@ func (h *WebhookHandler) CreateWebhook(c *gin.Context) {
c.JSON(http.StatusCreated, gin.H{"code": 0, "message": "success", "data": webhook})
}
// ListWebhooks 获取 Webhook 列表
// @Summary 获取 Webhook 列表
// @Description 获取当前用户的 Webhook 配置列表
// @Tags Webhook管理
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param page query int false "页码" default(1)
// @Param page_size query int false "每页数量" default(20)
// @Success 200 {object} Response "Webhook列表"
// @Failure 401 {object} Response "未认证"
// @Failure 500 {object} Response "服务器错误"
// @Router /api/v1/webhooks [get]
func (h *WebhookHandler) ListWebhooks(c *gin.Context) {
page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
pageSize, _ := strconv.Atoi(c.DefaultQuery("page_size", "20"))
@@ -70,6 +96,20 @@ func (h *WebhookHandler) ListWebhooks(c *gin.Context) {
})
}
// UpdateWebhook 更新 Webhook
// @Summary 更新 Webhook
// @Description 更新指定 Webhook 的配置
// @Tags Webhook管理
// @Accept json
// @Produce json
// @Security BearerAuth
// @Param id path int true "Webhook ID"
// @Param request body service.UpdateWebhookRequest true "更新信息"
// @Success 200 {object} Response "更新成功"
// @Failure 400 {object} Response "请求参数错误"
// @Failure 401 {object} Response "未认证"
// @Failure 500 {object} Response "服务器错误"
// @Router /api/v1/webhooks/{id} [put]
func (h *WebhookHandler) UpdateWebhook(c *gin.Context) {
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
if err != nil {
@@ -91,6 +131,18 @@ func (h *WebhookHandler) UpdateWebhook(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"code": 0, "message": "更新成功"})
}
// DeleteWebhook 删除 Webhook
// @Summary 删除 Webhook
// @Description 删除指定的 Webhook 配置
// @Tags Webhook管理
// @Produce json
// @Security BearerAuth
// @Param id path int true "Webhook ID"
// @Success 200 {object} Response "删除成功"
// @Failure 400 {object} Response "请求参数错误"
// @Failure 401 {object} Response "未认证"
// @Failure 500 {object} Response "服务器错误"
// @Router /api/v1/webhooks/{id} [delete]
func (h *WebhookHandler) DeleteWebhook(c *gin.Context) {
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
if err != nil {
@@ -106,6 +158,19 @@ func (h *WebhookHandler) DeleteWebhook(c *gin.Context) {
c.JSON(http.StatusOK, gin.H{"code": 0, "message": "删除成功"})
}
// GetWebhookDeliveries 获取 Webhook 投递记录
// @Summary 获取 Webhook 投递记录
// @Description 获取指定 Webhook 的最近投递记录
// @Tags Webhook管理
// @Produce json
// @Security BearerAuth
// @Param id path int true "Webhook ID"
// @Param limit query int false "返回记录数量" default(20)
// @Success 200 {object} Response "投递记录列表"
// @Failure 400 {object} Response "请求参数错误"
// @Failure 401 {object} Response "未认证"
// @Failure 500 {object} Response "服务器错误"
// @Router /api/v1/webhooks/{id}/deliveries [get]
func (h *WebhookHandler) GetWebhookDeliveries(c *gin.Context) {
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
if err != nil {