feat:add open platform more api

#664 #698

api/waf_account.go

@@ -6,6 +6,7 @@ import (
 	"SamWaf/model/common/response"
 	"SamWaf/model/request"
 	"errors"
+
 	"github.com/gin-gonic/gin"
 	"gorm.io/gorm"
 )
@@ -13,6 +14,7 @@ import (
 type WafAccountApi struct {
 }
 
+// AddApi 新增账号
 func (w *WafAccountApi) AddApi(c *gin.Context) {
 	var req request.WafAccountAddReq
 	err := c.ShouldBindJSON(&req)
@@ -36,6 +38,8 @@ func (w *WafAccountApi) AddApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetDetailApi 获取账号详情
 func (w *WafAccountApi) GetDetailApi(c *gin.Context) {
 	var req request.WafAccountDetailReq
 	err := c.ShouldBind(&req)
@@ -46,6 +50,8 @@ func (w *WafAccountApi) GetDetailApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetListApi 获取账号列表
 func (w *WafAccountApi) GetListApi(c *gin.Context) {
 	var req request.WafAccountSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -61,6 +67,8 @@ func (w *WafAccountApi) GetListApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// DelAccountApi 删除账号
 func (w *WafAccountApi) DelAccountApi(c *gin.Context) {
 	var req request.WafAccountDelReq
 	err := c.ShouldBind(&req)
@@ -79,6 +87,7 @@ func (w *WafAccountApi) DelAccountApi(c *gin.Context) {
 	}
 }
 
+// ModifyAccountApi 编辑账号
 func (w *WafAccountApi) ModifyAccountApi(c *gin.Context) {
 	var req request.WafAccountEditReq
 	err := c.ShouldBindJSON(&req)

api/waf_allow_ip.go

@@ -16,6 +16,16 @@ import (
 type WafAllowIpApi struct {
 }
 
+// AddApi 新增IP白名单
+// @Summary      新增IP白名单
+// @Description  为指定网站新增一条IP白名单记录（白名单IP绕过WAF检测）
+// @Tags         网站防护-IP白名单
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafAllowIpAddReq  true  "IP白名单配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/allowip/add [post]
 func (w *WafAllowIpApi) AddApi(c *gin.Context) {
 	var req request.WafAllowIpAddReq
 	err := c.ShouldBindJSON(&req)
@@ -40,6 +50,17 @@ func (w *WafAllowIpApi) AddApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetDetailApi 获取IP白名单详情
+// @Summary      获取IP白名单详情
+// @Description  根据ID获取IP白名单记录详情
+// @Tags         网站防护-IP白名单
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/allowip/detail [get]
 func (w *WafAllowIpApi) GetDetailApi(c *gin.Context) {
 	var req request.WafAllowIpDetailReq
 	err := c.ShouldBind(&req)
@@ -50,6 +71,17 @@ func (w *WafAllowIpApi) GetDetailApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetListApi 获取IP白名单列表
+// @Summary      获取IP白名单列表
+// @Description  分页查询IP白名单列表
+// @Tags         网站防护-IP白名单
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafAllowIpSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/allowip/list [post]
 func (w *WafAllowIpApi) GetListApi(c *gin.Context) {
 	var req request.WafAllowIpSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -65,6 +97,17 @@ func (w *WafAllowIpApi) GetListApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// DelAllowIpApi 删除IP白名单
+// @Summary      删除IP白名单
+// @Description  根据ID删除IP白名单记录
+// @Tags         网站防护-IP白名单
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/allowip/del [get]
 func (w *WafAllowIpApi) DelAllowIpApi(c *gin.Context) {
 	var req request.WafAllowIpDelReq
 	err := c.ShouldBind(&req)
@@ -85,6 +128,16 @@ func (w *WafAllowIpApi) DelAllowIpApi(c *gin.Context) {
 	}
 }
 
+// ModifyAllowIpApi 编辑IP白名单
+// @Summary      编辑IP白名单
+// @Description  修改IP白名单记录
+// @Tags         网站防护-IP白名单
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafAllowIpEditReq  true  "IP白名单配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/allowip/edit [post]
 func (w *WafAllowIpApi) ModifyAllowIpApi(c *gin.Context) {
 	var req request.WafAllowIpEditReq
 	err := c.ShouldBindJSON(&req)

api/waf_allow_url.go

@@ -16,6 +16,16 @@ import (
 type WafAllowUrlApi struct {
 }
 
+// AddApi 新增URL白名单
+// @Summary      新增URL白名单
+// @Description  为指定网站新增一条URL白名单记录（白名单URL绕过WAF检测）
+// @Tags         网站防护-URL白名单
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafAllowUrlAddReq  true  "URL白名单配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/allowurl/add [post]
 func (w *WafAllowUrlApi) AddApi(c *gin.Context) {
 	var req request.WafAllowUrlAddReq
 	err := c.ShouldBindJSON(&req)
@@ -40,6 +50,17 @@ func (w *WafAllowUrlApi) AddApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetDetailApi 获取URL白名单详情
+// @Summary      获取URL白名单详情
+// @Description  根据ID获取URL白名单记录详情
+// @Tags         网站防护-URL白名单
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/allowurl/detail [get]
 func (w *WafAllowUrlApi) GetDetailApi(c *gin.Context) {
 	var req request.WafAllowUrlDetailReq
 	err := c.ShouldBind(&req)
@@ -50,6 +71,17 @@ func (w *WafAllowUrlApi) GetDetailApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetListApi 获取URL白名单列表
+// @Summary      获取URL白名单列表
+// @Description  分页查询URL白名单列表
+// @Tags         网站防护-URL白名单
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafAllowUrlSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/allowurl/list [post]
 func (w *WafAllowUrlApi) GetListApi(c *gin.Context) {
 	var req request.WafAllowUrlSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -65,6 +97,17 @@ func (w *WafAllowUrlApi) GetListApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// DelAllowUrlApi 删除URL白名单
+// @Summary      删除URL白名单
+// @Description  根据ID删除URL白名单记录
+// @Tags         网站防护-URL白名单
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/allowurl/del [get]
 func (w *WafAllowUrlApi) DelAllowUrlApi(c *gin.Context) {
 	var req request.WafAllowUrlDelReq
 	err := c.ShouldBind(&req)
@@ -85,6 +128,16 @@ func (w *WafAllowUrlApi) DelAllowUrlApi(c *gin.Context) {
 	}
 }
 
+// ModifyAllowUrlApi 编辑URL白名单
+// @Summary      编辑URL白名单
+// @Description  修改URL白名单记录
+// @Tags         网站防护-URL白名单
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafAllowUrlEditReq  true  "URL白名单配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/allowurl/edit [post]
 func (w *WafAllowUrlApi) ModifyAllowUrlApi(c *gin.Context) {
 	var req request.WafAllowUrlEditReq
 	err := c.ShouldBindJSON(&req)

api/waf_anticc.go

@@ -20,6 +20,16 @@ import (
 type WafAntiCCApi struct {
 }
 
+// AddApi 新增CC防护规则
+// @Summary      新增CC防护规则
+// @Description  为指定网站新增一条CC防护规则（防止CC攻击）
+// @Tags         网站防护-CC防护
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafAntiCCAddReq  true  "CC防护规则配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/anticc/add [post]
 func (w *WafAntiCCApi) AddApi(c *gin.Context) {
 	ruleHelper := &utils.RuleHelper{}
 	var req request.WafAntiCCAddReq
@@ -60,6 +70,17 @@ func (w *WafAntiCCApi) AddApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetDetailApi 获取CC防护规则详情
+// @Summary      获取CC防护规则详情
+// @Description  根据ID获取CC防护规则详情
+// @Tags         网站防护-CC防护
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "规则ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/anticc/detail [get]
 func (w *WafAntiCCApi) GetDetailApi(c *gin.Context) {
 	var req request.WafAntiCCDetailReq
 	err := c.ShouldBind(&req)
@@ -70,6 +91,17 @@ func (w *WafAntiCCApi) GetDetailApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetListApi 获取CC防护规则列表
+// @Summary      获取CC防护规则列表
+// @Description  分页查询CC防护规则列表
+// @Tags         网站防护-CC防护
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafAntiCCSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/anticc/list [post]
 func (w *WafAntiCCApi) GetListApi(c *gin.Context) {
 	var req request.WafAntiCCSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -135,6 +167,17 @@ func (w *WafAntiCCApi) RemoveCCBanIPApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// DelAntiCCApi 删除CC防护规则
+// @Summary      删除CC防护规则
+// @Description  根据ID删除CC防护规则
+// @Tags         网站防护-CC防护
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "规则ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/anticc/del [get]
 func (w *WafAntiCCApi) DelAntiCCApi(c *gin.Context) {
 	var req request.WafAntiCCDelReq
 	err := c.ShouldBind(&req)
@@ -155,6 +198,16 @@ func (w *WafAntiCCApi) DelAntiCCApi(c *gin.Context) {
 	}
 }
 
+// ModifyAntiCCApi 编辑CC防护规则
+// @Summary      编辑CC防护规则
+// @Description  修改CC防护规则配置
+// @Tags         网站防护-CC防护
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafAntiCCEditReq  true  "CC防护规则配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/anticc/edit [post]
 func (w *WafAntiCCApi) ModifyAntiCCApi(c *gin.Context) {
 	ruleHelper := &utils.RuleHelper{}
 	var req request.WafAntiCCEditReq

api/waf_block_ip.go

@@ -16,6 +16,16 @@ import (
 type WafBlockIpApi struct {
 }
 
+// AddApi 新增IP黑名单
+// @Summary      新增IP黑名单
+// @Description  为指定网站新增一条IP黑名单记录
+// @Tags         网站防护-IP黑名单
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafBlockIpAddReq  true  "IP黑名单配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/blockip/add [post]
 func (w *WafBlockIpApi) AddApi(c *gin.Context) {
 	var req request.WafBlockIpAddReq
 	err := c.ShouldBindJSON(&req)
@@ -40,6 +50,17 @@ func (w *WafBlockIpApi) AddApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetDetailApi 获取IP黑名单详情
+// @Summary      获取IP黑名单详情
+// @Description  根据ID获取IP黑名单记录详情
+// @Tags         网站防护-IP黑名单
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/blockip/detail [get]
 func (w *WafBlockIpApi) GetDetailApi(c *gin.Context) {
 	var req request.WafBlockIpDetailReq
 	err := c.ShouldBind(&req)
@@ -50,6 +71,17 @@ func (w *WafBlockIpApi) GetDetailApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetListApi 获取IP黑名单列表
+// @Summary      获取IP黑名单列表
+// @Description  分页查询IP黑名单列表
+// @Tags         网站防护-IP黑名单
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafBlockIpSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/blockip/list [post]
 func (w *WafBlockIpApi) GetListApi(c *gin.Context) {
 	var req request.WafBlockIpSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -65,6 +97,17 @@ func (w *WafBlockIpApi) GetListApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// DelBlockIpApi 删除IP黑名单
+// @Summary      删除IP黑名单
+// @Description  根据ID删除IP黑名单记录
+// @Tags         网站防护-IP黑名单
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/blockip/del [get]
 func (w *WafBlockIpApi) DelBlockIpApi(c *gin.Context) {
 	var req request.WafBlockIpDelReq
 	err := c.ShouldBind(&req)
@@ -85,6 +128,16 @@ func (w *WafBlockIpApi) DelBlockIpApi(c *gin.Context) {
 	}
 }
 
+// ModifyBlockIpApi 编辑IP黑名单
+// @Summary      编辑IP黑名单
+// @Description  修改IP黑名单记录
+// @Tags         网站防护-IP黑名单
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafBlockIpEditReq  true  "IP黑名单配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/blockip/edit [post]
 func (w *WafBlockIpApi) ModifyBlockIpApi(c *gin.Context) {
 	var req request.WafBlockIpEditReq
 	err := c.ShouldBindJSON(&req)

api/waf_block_url.go

@@ -16,6 +16,16 @@ import (
 type WafBlockUrlApi struct {
 }
 
+// AddApi 新增URL黑名单
+// @Summary      新增URL黑名单
+// @Description  为指定网站新增一条URL黑名单记录（匹配该URL的请求将被拦截）
+// @Tags         网站防护-URL黑名单
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafBlockUrlAddReq  true  "URL黑名单配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/blockurl/add [post]
 func (w *WafBlockUrlApi) AddApi(c *gin.Context) {
 	var req request.WafBlockUrlAddReq
 	err := c.ShouldBindJSON(&req)
@@ -40,6 +50,17 @@ func (w *WafBlockUrlApi) AddApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetDetailApi 获取URL黑名单详情
+// @Summary      获取URL黑名单详情
+// @Description  根据ID获取URL黑名单记录详情
+// @Tags         网站防护-URL黑名单
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/blockurl/detail [get]
 func (w *WafBlockUrlApi) GetDetailApi(c *gin.Context) {
 	var req request.WafBlockUrlDetailReq
 	err := c.ShouldBind(&req)
@@ -50,6 +71,17 @@ func (w *WafBlockUrlApi) GetDetailApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetListApi 获取URL黑名单列表
+// @Summary      获取URL黑名单列表
+// @Description  分页查询URL黑名单列表
+// @Tags         网站防护-URL黑名单
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafBlockUrlSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/blockurl/list [post]
 func (w *WafBlockUrlApi) GetListApi(c *gin.Context) {
 	var req request.WafBlockUrlSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -65,6 +97,17 @@ func (w *WafBlockUrlApi) GetListApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// DelBlockUrlApi 删除URL黑名单
+// @Summary      删除URL黑名单
+// @Description  根据ID删除URL黑名单记录
+// @Tags         网站防护-URL黑名单
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/blockurl/del [get]
 func (w *WafBlockUrlApi) DelBlockUrlApi(c *gin.Context) {
 	var req request.WafBlockUrlDelReq
 	err := c.ShouldBind(&req)
@@ -85,6 +128,16 @@ func (w *WafBlockUrlApi) DelBlockUrlApi(c *gin.Context) {
 	}
 }
 
+// ModifyBlockUrlApi 编辑URL黑名单
+// @Summary      编辑URL黑名单
+// @Description  修改URL黑名单记录
+// @Tags         网站防护-URL黑名单
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafBlockUrlEditReq  true  "URL黑名单配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/blockurl/edit [post]
 func (w *WafBlockUrlApi) ModifyBlockUrlApi(c *gin.Context) {
 	var req request.WafBlockUrlEditReq
 	err := c.ShouldBindJSON(&req)

api/waf_cacherule_api.go

@@ -15,6 +15,16 @@ import (
 type WafCacheRuleApi struct {
 }
 
+// AddApi 新增缓存规则
+// @Summary      新增缓存规则
+// @Description  为指定网站新增一条缓存规则
+// @Tags         网站防护-缓存规则
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafCacheRuleAddReq  true  "缓存规则配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/cacherule/add [post]
 func (w *WafCacheRuleApi) AddApi(c *gin.Context) {
 	var req request.WafCacheRuleAddReq
 	err := c.ShouldBindJSON(&req)
@@ -40,6 +50,16 @@ func (w *WafCacheRuleApi) AddApi(c *gin.Context) {
 	}
 }
 
+// GetDetailApi 获取缓存规则详情
+// @Summary      获取缓存规则详情
+// @Description  根据ID获取缓存规则详情
+// @Tags         网站防护-缓存规则
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "规则ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/cacherule/detail [get]
 func (w *WafCacheRuleApi) GetDetailApi(c *gin.Context) {
 	var req request.WafCacheRuleDetailReq
 	err := c.ShouldBind(&req)
@@ -51,6 +71,16 @@ func (w *WafCacheRuleApi) GetDetailApi(c *gin.Context) {
 	}
 }
 
+// GetListApi 获取缓存规则列表
+// @Summary      获取缓存规则列表
+// @Description  分页查询缓存规则列表
+// @Tags         网站防护-缓存规则
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafCacheRuleSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/cacherule/list [post]
 func (w *WafCacheRuleApi) GetListApi(c *gin.Context) {
 	var req request.WafCacheRuleSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -67,6 +97,16 @@ func (w *WafCacheRuleApi) GetListApi(c *gin.Context) {
 	}
 }
 
+// DelApi 删除缓存规则
+// @Summary      删除缓存规则
+// @Description  根据ID删除缓存规则
+// @Tags         网站防护-缓存规则
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "规则ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/cacherule/del [get]
 func (w *WafCacheRuleApi) DelApi(c *gin.Context) {
 	var req request.WafCacheRuleDelReq
 	err := c.ShouldBind(&req)
@@ -90,6 +130,16 @@ func (w *WafCacheRuleApi) DelApi(c *gin.Context) {
 	}
 }
 
+// ModifyApi 编辑缓存规则
+// @Summary      编辑缓存规则
+// @Description  修改缓存规则配置
+// @Tags         网站防护-缓存规则
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafCacheRuleEditReq  true  "缓存规则配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/cacherule/edit [post]
 func (w *WafCacheRuleApi) ModifyApi(c *gin.Context) {
 	var req request.WafCacheRuleEditReq
 	err := c.ShouldBindJSON(&req)

api/waf_engine.go

@@ -9,6 +9,14 @@ import (
 type WafEngineApi struct {
 }
 
+// ResetWaf 重启WAF引擎
+// @Summary      重启WAF引擎
+// @Description  重启WAF引擎，重新加载所有规则和配置
+// @Tags         引擎-WAF引擎
+// @Produce      json
+// @Success      200  {object}  response.Response  "重启指令发起成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/engine/restart [post]
 func (w *WafEngineApi) ResetWaf(c *gin.Context) {
 	//重启WAF引擎
 	global.GWAF_CHAN_ENGINE <- 1

api/waf_firewall_ip_block_api.go

@@ -13,7 +13,16 @@ import (
 type WafFirewallIPBlockApi struct {
 }
 
-// AddApi 添加防火墙IP封禁
+// AddApi 新增防火墙IP封禁
+// @Summary      新增防火墙IP封禁
+// @Description  新增一条防火墙IP封禁规则（系统级别封禁，所有端口生效）
+// @Tags         防火墙-IP封禁
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafFirewallIPBlockAddReq  true  "IP封禁配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /firewallipblock/add [post]
 func (w *WafFirewallIPBlockApi) AddApi(c *gin.Context) {
 	var req request.WafFirewallIPBlockAddReq
 	err := c.ShouldBindJSON(&req)
@@ -45,6 +54,15 @@ func (w *WafFirewallIPBlockApi) GetDetailApi(c *gin.Context) {
 }
 
 // GetListApi 获取防火墙IP封禁列表
+// @Summary      获取防火墙IP封禁列表
+// @Description  分页查询防火墙IP封禁规则列表
+// @Tags         防火墙-IP封禁
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafFirewallIPBlockSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /firewallipblock/list [post]
 func (w *WafFirewallIPBlockApi) GetListApi(c *gin.Context) {
 	var req request.WafFirewallIPBlockSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -68,6 +86,15 @@ func (w *WafFirewallIPBlockApi) GetListApi(c *gin.Context) {
 }
 
 // DelApi 删除防火墙IP封禁
+// @Summary      删除防火墙IP封禁
+// @Description  根据ID删除防火墙IP封禁规则，同步从系统防火墙解除封禁
+// @Tags         防火墙-IP封禁
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "封禁记录ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /firewallipblock/del [get]
 func (w *WafFirewallIPBlockApi) DelApi(c *gin.Context) {
 	var req request.WafFirewallIPBlockDelReq
 	err := c.ShouldBind(&req)
@@ -86,7 +113,16 @@ func (w *WafFirewallIPBlockApi) DelApi(c *gin.Context) {
 	}
 }
 
-// ModifyApi 修改防火墙IP封禁
+// ModifyApi 编辑防火墙IP封禁
+// @Summary      编辑防火墙IP封禁
+// @Description  修改防火墙IP封禁规则
+// @Tags         防火墙-IP封禁
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafFirewallIPBlockEditReq  true  "IP封禁配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /firewallipblock/edit [post]
 func (w *WafFirewallIPBlockApi) ModifyApi(c *gin.Context) {
 	var req request.WafFirewallIPBlockEditReq
 	err := c.ShouldBindJSON(&req)

api/waf_host.go

@@ -253,6 +253,17 @@ func (w *WafHostAPi) GetDomainsByHostCodeApi(c *gin.Context) {
 	}
 
 }
+
+// DelHostApi 删除网站防护主机
+// @Summary      删除网站防护主机
+// @Description  根据 code 删除网站防护主机配置
+// @Tags         网站防护-主机管理
+// @Accept       json
+// @Produce      json
+// @Param        code  query     string  true  "主机唯一编码"
+// @Success      200   {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/host/del [get]
 func (w *WafHostAPi) DelHostApi(c *gin.Context) {
 	var req request.WafHostDelReq
 	err := c.ShouldBind(&req)
@@ -272,6 +283,16 @@ func (w *WafHostAPi) DelHostApi(c *gin.Context) {
 	}
 }
 
+// ModifyHostApi 编辑网站防护主机
+// @Summary      编辑网站防护主机
+// @Description  修改网站防护主机配置信息
+// @Tags         网站防护-主机管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafHostEditReq  true  "主机配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/host/edit [post]
 func (w *WafHostAPi) ModifyHostApi(c *gin.Context) {
 	var req request.WafHostEditReq
 	err := c.ShouldBindJSON(&req)
@@ -301,6 +322,17 @@ func (w *WafHostAPi) ModifyHostApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// ModifyGuardStatusApi 修改主机防御状态
+// @Summary      修改主机防御状态
+// @Description  开启或关闭指定主机的WAF防御
+// @Tags         网站防护-主机管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafHostGuardStatusReq  true  "防御状态参数"
+// @Success      200   {object}  response.Response  "状态更新成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/host/guardstatus [post]
 func (w *WafHostAPi) ModifyGuardStatusApi(c *gin.Context) {
 	var req request.WafHostGuardStatusReq
 	err := c.ShouldBind(&req)
@@ -365,10 +397,16 @@ func (w *WafHostAPi) ModifyAllGuardStatusApi(c *gin.Context) {
 	}
 }
 
-/*
-*
-修改启动状态
-*/
+// ModifyStartStatusApi 修改主机启动状态
+// @Summary      修改主机启动状态
+// @Description  启动或停止指定主机的监听服务
+// @Tags         网站防护-主机管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafHostStartStatusReq  true  "启动状态参数"
+// @Success      200   {object}  response.Response  "状态更新成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/host/startstatus [post]
 func (w *WafHostAPi) ModifyStartStatusApi(c *gin.Context) {
 	var req request.WafHostStartStatusReq
 	err := c.ShouldBind(&req)

api/waf_ip_failure.go

@@ -19,6 +19,13 @@ type WafIPFailureApi struct {
 }
 
 // GetConfigApi 获取IP失败封禁配置
+// @Summary      获取IP失败封禁配置
+// @Description  获取IP失败封禁全局配置（启用状态、状态码、锁定时间等）
+// @Tags         网站防护-IP失败封禁
+// @Produce      json
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/ipfailure/config [get]
 func (w *WafIPFailureApi) GetConfigApi(c *gin.Context) {
 	var req request.WafIPFailureConfigReq
 	err := c.ShouldBind(&req)
@@ -35,6 +42,15 @@ func (w *WafIPFailureApi) GetConfigApi(c *gin.Context) {
 }
 
 // SetConfigApi 设置IP失败封禁配置
+// @Summary      设置IP失败封禁配置
+// @Description  更新IP失败封禁全局配置
+// @Tags         网站防护-IP失败封禁
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafIPFailureSetConfigReq  true  "配置参数"
+// @Success      200   {object}  response.Response  "设置成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/ipfailure/setconfig [post]
 func (w *WafIPFailureApi) SetConfigApi(c *gin.Context) {
 	var req request.WafIPFailureSetConfigReq
 	err := c.ShouldBindJSON(&req)
@@ -85,7 +101,14 @@ func (w *WafIPFailureApi) SetConfigApi(c *gin.Context) {
 	}
 }
 
-// GetBanIpListApi 获取被封禁的IP列表
+// GetBanIpListApi 获取IP失败封禁列表
+// @Summary      获取IP失败封禁列表
+// @Description  获取当前因请求失败次数超限而被封禁的IP列表
+// @Tags         网站防护-IP失败封禁
+// @Produce      json
+// @Success      200  {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/ipfailure/baniplist [get]
 func (w *WafIPFailureApi) GetBanIpListApi(c *gin.Context) {
 	// 获取所有IP失败记录
 	banIpList := global.GCACHE_WAFCACHE.ListAvailableKeysWithPrefix(enums.CACHE_IP_FAILURE_PRE)

api/waf_loadbalance.go

@@ -14,6 +14,16 @@ import (
 type WafLoadBalanceApi struct {
 }
 
+// AddApi 新增负载均衡节点
+// @Summary      新增负载均衡节点
+// @Description  为指定网站新增一条后端负载均衡节点配置
+// @Tags         网站防护-负载均衡
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafLoadBalanceAddReq  true  "负载均衡节点配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/loadbalance/add [post]
 func (w *WafLoadBalanceApi) AddApi(c *gin.Context) {
 	var req request.WafLoadBalanceAddReq
 	err := c.ShouldBindJSON(&req)
@@ -38,6 +48,17 @@ func (w *WafLoadBalanceApi) AddApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetDetailApi 获取负载均衡节点详情
+// @Summary      获取负载均衡节点详情
+// @Description  根据ID获取负载均衡节点配置详情
+// @Tags         网站防护-负载均衡
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "节点ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/loadbalance/detail [get]
 func (w *WafLoadBalanceApi) GetDetailApi(c *gin.Context) {
 	var req request.WafLoadBalanceDetailReq
 	err := c.ShouldBind(&req)
@@ -48,6 +69,17 @@ func (w *WafLoadBalanceApi) GetDetailApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetListApi 获取负载均衡节点列表
+// @Summary      获取负载均衡节点列表
+// @Description  分页查询负载均衡节点列表
+// @Tags         网站防护-负载均衡
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafLoadBalanceSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/loadbalance/list [post]
 func (w *WafLoadBalanceApi) GetListApi(c *gin.Context) {
 	var req request.WafLoadBalanceSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -63,6 +95,17 @@ func (w *WafLoadBalanceApi) GetListApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// DelLoadBalanceApi 删除负载均衡节点
+// @Summary      删除负载均衡节点
+// @Description  根据ID删除负载均衡后端节点
+// @Tags         网站防护-负载均衡
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "节点ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/loadbalance/del [get]
 func (w *WafLoadBalanceApi) DelLoadBalanceApi(c *gin.Context) {
 	var req request.WafLoadBalanceDelReq
 	err := c.ShouldBind(&req)
@@ -83,6 +126,16 @@ func (w *WafLoadBalanceApi) DelLoadBalanceApi(c *gin.Context) {
 	}
 }
 
+// ModifyApi 编辑负载均衡节点
+// @Summary      编辑负载均衡节点
+// @Description  修改负载均衡后端节点配置
+// @Tags         网站防护-负载均衡
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafLoadBalanceEditReq  true  "负载均衡节点配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/loadbalance/edit [post]
 func (w *WafLoadBalanceApi) ModifyApi(c *gin.Context) {
 	var req request.WafLoadBalanceEditReq
 	err := c.ShouldBindJSON(&req)

api/waf_logfilewrite.go

@@ -12,6 +12,15 @@ type WafLogFileWriteApi struct {
 }
 
 // GetPreviewApi 获取日志文件预览（最新N行）
+// @Summary      获取日志文件预览
+// @Description  获取通知日志文件最新 N 行内容，lines 范围 1-500，默认 100
+// @Tags         日志文件写入
+// @Accept       json
+// @Produce      json
+// @Param        lines  query     int  false  "行数（1-500，默认100）"
+// @Success      200    {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /logfilewrite/preview [get]
 func (w *WafLogFileWriteApi) GetPreviewApi(c *gin.Context) {
 	linesStr := c.DefaultQuery("lines", "100")
 	lines, err := strconv.Atoi(linesStr)
@@ -44,6 +53,14 @@ func (w *WafLogFileWriteApi) GetPreviewApi(c *gin.Context) {
 }
 
 // GetCurrentFileInfoApi 获取当前日志文件信息
+// @Summary      获取当前日志文件信息
+// @Description  获取当前通知日志文件的路径、大小等信息
+// @Tags         日志文件写入
+// @Accept       json
+// @Produce      json
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /logfilewrite/currentfile [get]
 func (w *WafLogFileWriteApi) GetCurrentFileInfoApi(c *gin.Context) {
 	writer := getLogFileWriter()
 	if writer == nil {
@@ -61,6 +78,14 @@ func (w *WafLogFileWriteApi) GetCurrentFileInfoApi(c *gin.Context) {
 }
 
 // GetBackupFilesApi 获取备份文件列表
+// @Summary      获取日志备份文件列表
+// @Description  获取所有已归档的日志备份文件信息列表
+// @Tags         日志文件写入
+// @Accept       json
+// @Produce      json
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /logfilewrite/backupfiles [get]
 func (w *WafLogFileWriteApi) GetBackupFilesApi(c *gin.Context) {
 	writer := getLogFileWriter()
 	if writer == nil {
@@ -78,6 +103,14 @@ func (w *WafLogFileWriteApi) GetBackupFilesApi(c *gin.Context) {
 }
 
 // ClearLogFileApi 清空当前日志文件
+// @Summary      清空当前日志文件
+// @Description  清空当前通知日志文件的所有内容
+// @Tags         日志文件写入
+// @Accept       json
+// @Produce      json
+// @Success      200  {object}  response.Response  "清空成功"
+// @Security     ApiKeyAuth
+// @Router       /logfilewrite/clear [post]
 func (w *WafLogFileWriteApi) ClearLogFileApi(c *gin.Context) {
 	writer := getLogFileWriter()
 	if writer == nil {
@@ -95,6 +128,14 @@ func (w *WafLogFileWriteApi) ClearLogFileApi(c *gin.Context) {
 }
 
 // GetTemplateVariablesApi 获取可用的模板变量列表
+// @Summary      获取日志模板变量列表
+// @Description  获取日志文件写入模板中可用的所有变量名称及说明
+// @Tags         日志文件写入
+// @Accept       json
+// @Produce      json
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /logfilewrite/variables [get]
 func (w *WafLogFileWriteApi) GetTemplateVariablesApi(c *gin.Context) {
 	variables := logfilewriter.GetTemplateVariables()
 	response.OkWithDetailed(variables, "获取成功", c)

api/waf_notify_channel.go

@@ -13,7 +13,16 @@ type WafNotifyChannelApi struct{}
 
 var wafNotifyChannelService = waf_service.WafNotifyChannelServiceApp
 
-// AddApi 添加通知渠道
+// AddApi 新增通知渠道
+// @Summary      新增通知渠道
+// @Description  新增一个通知渠道（支持企业微信、钉钉、Server酱等）
+// @Tags         通知-渠道
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafNotifyChannelAddReq  true  "通知渠道配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /notify/channel/add [post]
 func (w *WafNotifyChannelApi) AddApi(c *gin.Context) {
 	var req request.WafNotifyChannelAddReq
 	err := c.ShouldBindJSON(&req)
@@ -37,6 +46,15 @@ func (w *WafNotifyChannelApi) AddApi(c *gin.Context) {
 }
 
 // GetDetailApi 获取通知渠道详情
+// @Summary      获取通知渠道详情
+// @Description  根据ID获取通知渠道详情
+// @Tags         通知-渠道
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "渠道ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /notify/channel/detail [get]
 func (w *WafNotifyChannelApi) GetDetailApi(c *gin.Context) {
 	var req request.WafNotifyChannelDetailReq
 	err := c.ShouldBind(&req)
@@ -49,6 +67,15 @@ func (w *WafNotifyChannelApi) GetDetailApi(c *gin.Context) {
 }
 
 // GetListApi 获取通知渠道列表
+// @Summary      获取通知渠道列表
+// @Description  分页查询通知渠道列表
+// @Tags         通知-渠道
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafNotifyChannelSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /notify/channel/list [post]
 func (w *WafNotifyChannelApi) GetListApi(c *gin.Context) {
 	var req request.WafNotifyChannelSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -66,6 +93,15 @@ func (w *WafNotifyChannelApi) GetListApi(c *gin.Context) {
 }
 
 // DelApi 删除通知渠道
+// @Summary      删除通知渠道
+// @Description  根据ID删除通知渠道
+// @Tags         通知-渠道
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "渠道ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /notify/channel/del [get]
 func (w *WafNotifyChannelApi) DelApi(c *gin.Context) {
 	var req request.WafNotifyChannelDelReq
 	err := c.ShouldBind(&req)
@@ -83,7 +119,16 @@ func (w *WafNotifyChannelApi) DelApi(c *gin.Context) {
 	}
 }
 
-// ModifyApi 修改通知渠道
+// ModifyApi 编辑通知渠道
+// @Summary      编辑通知渠道
+// @Description  修改通知渠道配置
+// @Tags         通知-渠道
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafNotifyChannelEditReq  true  "通知渠道配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /notify/channel/edit [post]
 func (w *WafNotifyChannelApi) ModifyApi(c *gin.Context) {
 	var req request.WafNotifyChannelEditReq
 	err := c.ShouldBindJSON(&req)

api/waf_notify_log.go

@@ -14,6 +14,15 @@ type WafNotifyLogApi struct{}
 var wafNotifyLogService = waf_service.WafNotifyLogServiceApp
 
 // GetListApi 获取通知日志列表
+// @Summary      获取通知日志列表
+// @Description  分页查询通知发送日志列表
+// @Tags         通知日志
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafNotifyLogSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /notify/log/list [post]
 func (w *WafNotifyLogApi) GetListApi(c *gin.Context) {
 	var req request.WafNotifyLogSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -31,6 +40,15 @@ func (w *WafNotifyLogApi) GetListApi(c *gin.Context) {
 }
 
 // GetDetailApi 获取通知日志详情
+// @Summary      获取通知日志详情
+// @Description  根据ID获取单条通知日志详情
+// @Tags         通知日志
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "日志ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /notify/log/detail [get]
 func (w *WafNotifyLogApi) GetDetailApi(c *gin.Context) {
 	var req request.WafNotifyLogDetailReq
 	err := c.ShouldBind(&req)
@@ -43,6 +61,15 @@ func (w *WafNotifyLogApi) GetDetailApi(c *gin.Context) {
 }
 
 // DelApi 删除通知日志
+// @Summary      删除通知日志
+// @Description  根据ID删除指定通知日志记录
+// @Tags         通知日志
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "日志ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /notify/log/del [get]
 func (w *WafNotifyLogApi) DelApi(c *gin.Context) {
 	var req request.WafNotifyLogDelReq
 	err := c.ShouldBind(&req)

api/waf_notify_subscription.go

@@ -13,7 +13,16 @@ type WafNotifySubscriptionApi struct{}
 
 var wafNotifySubscriptionService = waf_service.WafNotifySubscriptionServiceApp
 
-// AddApi 添加通知订阅
+// AddApi 新增通知订阅
+// @Summary      新增通知订阅
+// @Description  新增一条通知订阅，将事件类型与渠道关联
+// @Tags         通知-订阅
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafNotifySubscriptionAddReq  true  "通知订阅配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /notify/subscription/add [post]
 func (w *WafNotifySubscriptionApi) AddApi(c *gin.Context) {
 	var req request.WafNotifySubscriptionAddReq
 	err := c.ShouldBindJSON(&req)
@@ -49,6 +58,15 @@ func (w *WafNotifySubscriptionApi) GetDetailApi(c *gin.Context) {
 }
 
 // GetListApi 获取通知订阅列表
+// @Summary      获取通知订阅列表
+// @Description  分页查询通知订阅列表
+// @Tags         通知-订阅
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafNotifySubscriptionSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /notify/subscription/list [post]
 func (w *WafNotifySubscriptionApi) GetListApi(c *gin.Context) {
 	var req request.WafNotifySubscriptionSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -66,6 +84,15 @@ func (w *WafNotifySubscriptionApi) GetListApi(c *gin.Context) {
 }
 
 // DelApi 删除通知订阅
+// @Summary      删除通知订阅
+// @Description  根据ID删除通知订阅
+// @Tags         通知-订阅
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "订阅ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /notify/subscription/del [get]
 func (w *WafNotifySubscriptionApi) DelApi(c *gin.Context) {
 	var req request.WafNotifySubscriptionDelReq
 	err := c.ShouldBind(&req)

api/waf_onekeymod.go

@@ -12,6 +12,16 @@ import (
 type WafOneKeyModApi struct {
 }
 
+// GetDetailApi 获取一键修改记录详情
+// @Summary      获取一键修改记录详情
+// @Description  根据ID获取一键修改记录详情
+// @Tags         一键修改
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/onekeymod/detail [get]
 func (w *WafOneKeyModApi) GetDetailApi(c *gin.Context) {
 	var req request.WafOneKeyModDetailReq
 	err := c.ShouldBind(&req)
@@ -22,6 +32,17 @@ func (w *WafOneKeyModApi) GetDetailApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetListApi 获取一键修改记录列表
+// @Summary      获取一键修改记录列表
+// @Description  分页查询一键修改历史记录列表
+// @Tags         一键修改
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafOneKeyModSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/onekeymod/list [post]
 func (w *WafOneKeyModApi) GetListApi(c *gin.Context) {
 	var req request.WafOneKeyModSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -37,6 +58,17 @@ func (w *WafOneKeyModApi) GetListApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// DelApi 删除一键修改记录
+// @Summary      删除一键修改记录
+// @Description  根据ID删除一键修改历史记录
+// @Tags         一键修改
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/onekeymod/del [get]
 func (w *WafOneKeyModApi) DelApi(c *gin.Context) {
 	var req request.WafOneKeyModDelReq
 	err := c.ShouldBind(&req)
@@ -55,6 +87,16 @@ func (w *WafOneKeyModApi) DelApi(c *gin.Context) {
 	}
 }
 
+// DoOneKeyModifyApi 执行一键修改
+// @Summary      执行一键修改
+// @Description  对指定文件路径执行一键批量修改操作
+// @Tags         一键修改
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafDoOneKeyModReq  true  "一键修改参数"
+// @Success      200   {object}  response.Response  "修改成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/onekeymod/doModify [post]
 func (w *WafOneKeyModApi) DoOneKeyModifyApi(c *gin.Context) {
 	var req request.WafDoOneKeyModReq
 	err := c.ShouldBindJSON(&req)
@@ -70,6 +112,17 @@ func (w *WafOneKeyModApi) DoOneKeyModifyApi(c *gin.Context) {
 		response.FailWithMessage("修改失败", c)
 	}
 }
+
+// RestoreApi 还原一键修改
+// @Summary      还原一键修改
+// @Description  根据ID还原指定的一键修改记录到原始状态
+// @Tags         一键修改
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "还原成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/onekeymod/restore [get]
 func (w *WafOneKeyModApi) RestoreApi(c *gin.Context) {
 	var req request.WafOneKeyModRestoreReq
 	err := c.ShouldBind(&req)

api/waf_oplatform_key.go

@@ -8,6 +8,7 @@ import (
 
 type WafOPlatformKeyApi struct{}
 
+// AddApi 新增OpenAPI Key
 func (w *WafOPlatformKeyApi) AddApi(c *gin.Context) {
 	var req request.WafOPlatformKeyAddReq
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -26,6 +27,7 @@ func (w *WafOPlatformKeyApi) AddApi(c *gin.Context) {
 	response.OkWithDetailed(gin.H{"id": id, "api_key": apiKey}, "添加成功", c)
 }
 
+// ModifyApi 编辑OpenAPI Key
 func (w *WafOPlatformKeyApi) ModifyApi(c *gin.Context) {
 	var req request.WafOPlatformKeyEditReq
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -39,6 +41,7 @@ func (w *WafOPlatformKeyApi) ModifyApi(c *gin.Context) {
 	response.OkWithMessage("修改成功", c)
 }
 
+// DelApi 删除OpenAPI Key
 func (w *WafOPlatformKeyApi) DelApi(c *gin.Context) {
 	var req request.WafOPlatformKeyDelReq
 	if err := c.ShouldBindQuery(&req); err != nil {
@@ -52,6 +55,7 @@ func (w *WafOPlatformKeyApi) DelApi(c *gin.Context) {
 	response.OkWithMessage("删除成功", c)
 }
 
+// GetDetailApi 获取OpenAPI Key详情
 func (w *WafOPlatformKeyApi) GetDetailApi(c *gin.Context) {
 	var req request.WafOPlatformKeyDetailReq
 	if err := c.ShouldBindQuery(&req); err != nil {
@@ -62,6 +66,7 @@ func (w *WafOPlatformKeyApi) GetDetailApi(c *gin.Context) {
 	response.OkWithData(bean, c)
 }
 
+// GetListApi 获取OpenAPI Key列表
 func (w *WafOPlatformKeyApi) GetListApi(c *gin.Context) {
 	var req request.WafOPlatformKeySearchReq
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -87,6 +92,7 @@ func (w *WafOPlatformKeyApi) GetListApi(c *gin.Context) {
 	}, "查询成功", c)
 }
 
+// ResetSecretApi 重置OpenAPI Key
 func (w *WafOPlatformKeyApi) ResetSecretApi(c *gin.Context) {
 	var req request.WafOPlatformKeyResetSecretReq
 	if err := c.ShouldBindJSON(&req); err != nil {

api/waf_oplatform_log.go

@@ -8,6 +8,7 @@ import (
 
 type WafOPlatformLogApi struct{}
 
+// GetDetailApi 获取OpenAPI调用日志详情
 func (w *WafOPlatformLogApi) GetDetailApi(c *gin.Context) {
 	var req request.WafOPlatformLogDetailReq
 	if err := c.ShouldBindQuery(&req); err != nil {
@@ -18,6 +19,7 @@ func (w *WafOPlatformLogApi) GetDetailApi(c *gin.Context) {
 	response.OkWithData(bean, c)
 }
 
+// GetListApi 获取OpenAPI调用日志列表
 func (w *WafOPlatformLogApi) GetListApi(c *gin.Context) {
 	var req request.WafOPlatformLogSearchReq
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -43,6 +45,7 @@ func (w *WafOPlatformLogApi) GetListApi(c *gin.Context) {
 	}, "查询成功", c)
 }
 
+// DelApi 删除OpenAPI调用日志
 func (w *WafOPlatformLogApi) DelApi(c *gin.Context) {
 	var req request.WafOPlatformLogDelReq
 	if err := c.ShouldBindQuery(&req); err != nil {

api/waf_privategroup_api.go

@@ -11,6 +11,16 @@ import (
 type WafPrivateGroupApi struct {
 }
 
+// AddApi 新增私有分组
+// @Summary      新增私有分组
+// @Description  新增一个私有信息分组
+// @Tags         私有分组管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafPrivateGroupAddReq  true  "分组配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/privategroup/add [post]
 func (w *WafPrivateGroupApi) AddApi(c *gin.Context) {
 	var req request.WafPrivateGroupAddReq
 	err := c.ShouldBindJSON(&req)
@@ -35,6 +45,16 @@ func (w *WafPrivateGroupApi) AddApi(c *gin.Context) {
 	}
 }
 
+// GetDetailApi 获取私有分组详情
+// @Summary      获取私有分组详情
+// @Description  根据ID获取私有分组详情
+// @Tags         私有分组管理
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "分组ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/privategroup/detail [get]
 func (w *WafPrivateGroupApi) GetDetailApi(c *gin.Context) {
 	var req request.WafPrivateGroupDetailReq
 	err := c.ShouldBind(&req)
@@ -46,6 +66,16 @@ func (w *WafPrivateGroupApi) GetDetailApi(c *gin.Context) {
 	}
 }
 
+// GetListApi 获取私有分组列表
+// @Summary      获取私有分组列表
+// @Description  分页查询私有分组列表
+// @Tags         私有分组管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafPrivateGroupSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/privategroup/list [post]
 func (w *WafPrivateGroupApi) GetListApi(c *gin.Context) {
 	var req request.WafPrivateGroupSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -62,6 +92,16 @@ func (w *WafPrivateGroupApi) GetListApi(c *gin.Context) {
 	}
 }
 
+// GetListByBelongCloudApi 按云环境查询私有分组列表
+// @Summary      按云环境查询私有分组列表
+// @Description  根据所属云环境分页查询私有分组列表
+// @Tags         私有分组管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafPrivateGroupSearchByCloudReq  true  "查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/privategroup/listbybelongcloud [post]
 func (w *WafPrivateGroupApi) GetListByBelongCloudApi(c *gin.Context) {
 	var req request.WafPrivateGroupSearchByCloudReq
 	err := c.ShouldBindJSON(&req)
@@ -78,6 +118,16 @@ func (w *WafPrivateGroupApi) GetListByBelongCloudApi(c *gin.Context) {
 	}
 }
 
+// DelApi 删除私有分组
+// @Summary      删除私有分组
+// @Description  根据ID删除私有分组
+// @Tags         私有分组管理
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "分组ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/privategroup/del [get]
 func (w *WafPrivateGroupApi) DelApi(c *gin.Context) {
 	var req request.WafPrivateGroupDelReq
 	err := c.ShouldBind(&req)
@@ -95,6 +145,16 @@ func (w *WafPrivateGroupApi) DelApi(c *gin.Context) {
 	}
 }
 
+// ModifyApi 编辑私有分组
+// @Summary      编辑私有分组
+// @Description  修改私有分组信息
+// @Tags         私有分组管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafPrivateGroupEditReq  true  "分组配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/privategroup/edit [post]
 func (w *WafPrivateGroupApi) ModifyApi(c *gin.Context) {
 	var req request.WafPrivateGroupEditReq
 	err := c.ShouldBindJSON(&req)

api/waf_privateinfo_api.go

@@ -14,6 +14,16 @@ import (
 type WafPrivateInfoApi struct {
 }
 
+// AddApi 新增私有信息
+// @Summary      新增私有信息
+// @Description  新增一条私有配置信息（如 API Key、密码等敏感数据）
+// @Tags         私有信息管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafPrivateInfoAddReq  true  "私有信息配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/privateinfo/add [post]
 func (w *WafPrivateInfoApi) AddApi(c *gin.Context) {
 	var req request.WafPrivateInfoAddReq
 	err := c.ShouldBindJSON(&req)
@@ -38,6 +48,16 @@ func (w *WafPrivateInfoApi) AddApi(c *gin.Context) {
 	}
 }
 
+// GetDetailApi 获取私有信息详情
+// @Summary      获取私有信息详情
+// @Description  根据ID获取私有信息详情，敏感值字段自动脱敏
+// @Tags         私有信息管理
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/privateinfo/detail [get]
 func (w *WafPrivateInfoApi) GetDetailApi(c *gin.Context) {
 	var req request.WafPrivateInfoDetailReq
 	err := c.ShouldBind(&req)
@@ -55,6 +75,16 @@ func (w *WafPrivateInfoApi) GetDetailApi(c *gin.Context) {
 	}
 }
 
+// GetListApi 获取私有信息列表
+// @Summary      获取私有信息列表
+// @Description  分页查询私有信息列表，敏感值字段自动脱敏
+// @Tags         私有信息管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafPrivateInfoSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/privateinfo/list [post]
 func (w *WafPrivateInfoApi) GetListApi(c *gin.Context) {
 	var req request.WafPrivateInfoSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -77,6 +107,16 @@ func (w *WafPrivateInfoApi) GetListApi(c *gin.Context) {
 	}
 }
 
+// DelApi 删除私有信息
+// @Summary      删除私有信息
+// @Description  根据ID删除私有信息，同时清除对应的环境变量
+// @Tags         私有信息管理
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/privateinfo/del [get]
 func (w *WafPrivateInfoApi) DelApi(c *gin.Context) {
 	var req request.WafPrivateInfoDelReq
 	err := c.ShouldBind(&req)
@@ -100,6 +140,16 @@ func (w *WafPrivateInfoApi) DelApi(c *gin.Context) {
 	}
 }
 
+// ModifyApi 编辑私有信息
+// @Summary      编辑私有信息
+// @Description  修改私有信息，若值为"****"则保留原值不更新
+// @Tags         私有信息管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafPrivateInfoEditReq  true  "私有信息配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/privateinfo/edit [post]
 func (w *WafPrivateInfoApi) ModifyApi(c *gin.Context) {
 	var req request.WafPrivateInfoEditReq
 	err := c.ShouldBindJSON(&req)

api/waf_rule.go

@@ -23,6 +23,16 @@ import (
 type WafRuleAPi struct {
 }
 
+// AddApi 新增WAF规则
+// @Summary      新增WAF规则
+// @Description  新增一条WAF防护规则
+// @Tags         网站防护-规则管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafRuleAddReq  true  "规则配置"
+// @Success      200   {object}  response.Response{data=string}  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/rule/add [post]
 func (w *WafRuleAPi) AddApi(c *gin.Context) {
 	ruleHelper := &utils.RuleHelper{}
 	var req request.WafRuleAddReq
@@ -93,6 +103,17 @@ func (w *WafRuleAPi) AddApi(c *gin.Context) {
 		return
 	}
 }
+
+// GetDetailApi 获取WAF规则详情
+// @Summary      获取WAF规则详情
+// @Description  根据 code 获取单条WAF规则详情
+// @Tags         网站防护-规则管理
+// @Accept       json
+// @Produce      json
+// @Param        code  query     string  true  "规则唯一编码"
+// @Success      200   {object}  response.Response{data=model.Rules}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/rule/detail [get]
 func (w *WafRuleAPi) GetDetailApi(c *gin.Context) {
 	var req request.WafRuleDetailReq
 	err := c.ShouldBind(&req)
@@ -103,6 +124,17 @@ func (w *WafRuleAPi) GetDetailApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetListApi 获取WAF规则列表
+// @Summary      获取WAF规则列表
+// @Description  分页查询WAF防护规则列表
+// @Tags         网站防护-规则管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafRuleSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/rule/list [post]
 func (w *WafRuleAPi) GetListApi(c *gin.Context) {
 	var req request.WafRuleSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -134,6 +166,17 @@ func (w *WafRuleAPi) GetListByHostCodeApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// DelRuleApi 删除WAF规则
+// @Summary      删除WAF规则
+// @Description  根据 code 删除WAF防护规则
+// @Tags         网站防护-规则管理
+// @Accept       json
+// @Produce      json
+// @Param        code  query     string  true  "规则唯一编码"
+// @Success      200   {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/rule/del [get]
 func (w *WafRuleAPi) DelRuleApi(c *gin.Context) {
 	var req request.WafRuleDelReq
 	err := c.ShouldBind(&req)
@@ -156,6 +199,16 @@ func (w *WafRuleAPi) DelRuleApi(c *gin.Context) {
 	}
 }
 
+// ModifyRuleApi 编辑WAF规则
+// @Summary      编辑WAF规则
+// @Description  修改已有WAF防护规则配置
+// @Tags         网站防护-规则管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafRuleEditReq  true  "规则配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/rule/edit [post]
 func (w *WafRuleAPi) ModifyRuleApi(c *gin.Context) {
 	ruleHelper := &utils.RuleHelper{}
 	var req request.WafRuleEditReq
@@ -326,7 +379,16 @@ func (w *WafRuleAPi) FormatRuleApi(c *gin.Context) {
 	}, "获取成功", c)
 }
 
-// ModifyRuleStatusApi 修改规则状态
+// ModifyRuleStatusApi 修改WAF规则状态
+// @Summary      修改WAF规则状态
+// @Description  启用或禁用WAF防护规则
+// @Tags         网站防护-规则管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafRuleStatusReq  true  "状态参数"
+// @Success      200   {object}  response.Response  "状态更新成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/rule/status [post]
 func (w *WafRuleAPi) ModifyRuleStatusApi(c *gin.Context) {
 	var req request.WafRuleStatusReq
 	err := c.ShouldBind(&req)

api/waf_sensitive.go

@@ -13,6 +13,16 @@ import (
 type WafSensitiveApi struct {
 }
 
+// AddApi 新增敏感词
+// @Summary      新增敏感词
+// @Description  新增一条敏感词记录（用于响应内容过滤和替换）
+// @Tags         网站防护-敏感词
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafSensitiveAddReq  true  "敏感词配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sensitive/add [post]
 func (w *WafSensitiveApi) AddApi(c *gin.Context) {
 	var req request.WafSensitiveAddReq
 	err := c.ShouldBindJSON(&req)
@@ -37,6 +47,17 @@ func (w *WafSensitiveApi) AddApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetDetailApi 获取敏感词详情
+// @Summary      获取敏感词详情
+// @Description  根据ID获取敏感词记录详情
+// @Tags         网站防护-敏感词
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sensitive/detail [get]
 func (w *WafSensitiveApi) GetDetailApi(c *gin.Context) {
 	var req request.WafSensitiveDetailReq
 	err := c.ShouldBind(&req)
@@ -47,6 +68,17 @@ func (w *WafSensitiveApi) GetDetailApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetListApi 获取敏感词列表
+// @Summary      获取敏感词列表
+// @Description  分页查询敏感词列表
+// @Tags         网站防护-敏感词
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafSensitiveSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sensitive/list [post]
 func (w *WafSensitiveApi) GetListApi(c *gin.Context) {
 	var req request.WafSensitiveSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -62,6 +94,17 @@ func (w *WafSensitiveApi) GetListApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// DelSensitiveApi 删除敏感词
+// @Summary      删除敏感词
+// @Description  根据ID删除敏感词记录
+// @Tags         网站防护-敏感词
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sensitive/del [get]
 func (w *WafSensitiveApi) DelSensitiveApi(c *gin.Context) {
 	var req request.WafSensitiveDelReq
 	err := c.ShouldBind(&req)
@@ -121,6 +164,17 @@ func (w *WafSensitiveApi) DelAllSensitiveApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// ModifySensitiveApi 编辑敏感词
+// @Summary      编辑敏感词
+// @Description  修改敏感词记录
+// @Tags         网站防护-敏感词
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafSensitiveEditReq  true  "敏感词配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sensitive/edit [post]
 func (w *WafSensitiveApi) ModifySensitiveApi(c *gin.Context) {
 	var req request.WafSensitiveEditReq
 	err := c.ShouldBindJSON(&req)

api/waf_ssl.go

@@ -15,7 +15,16 @@ import (
 
 type WafSslConfigApi struct{}
 
-// AddSslConfigApi 添加SSL证书
+// AddSslConfigApi 新增SSL证书
+// @Summary      新增SSL证书
+// @Description  上传并保存SSL证书（PEM格式的证书和私钥）
+// @Tags         SSL-证书配置
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.SslConfigAddReq  true  "SSL证书配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslconfig/add [post]
 func (s *WafSslConfigApi) AddSslConfigApi(c *gin.Context) {
 	var req request.SslConfigAddReq
 	err := c.ShouldBindJSON(&req)
@@ -33,6 +42,15 @@ func (s *WafSslConfigApi) AddSslConfigApi(c *gin.Context) {
 }
 
 // GetSslConfigDetailApi 获取SSL证书详情
+// @Summary      获取SSL证书详情
+// @Description  根据ID获取SSL证书详情
+// @Tags         SSL-证书配置
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "证书ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslconfig/detail [get]
 func (s *WafSslConfigApi) GetSslConfigDetailApi(c *gin.Context) {
 	var req request.SslConfigDetailReq
 	err := c.ShouldBind(&req)
@@ -45,6 +63,15 @@ func (s *WafSslConfigApi) GetSslConfigDetailApi(c *gin.Context) {
 }
 
 // GetSslConfigListApi 获取SSL证书列表
+// @Summary      获取SSL证书列表
+// @Description  分页查询SSL证书列表
+// @Tags         SSL-证书配置
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.SslConfigSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslconfig/list [post]
 func (s *WafSslConfigApi) GetSslConfigListApi(c *gin.Context) {
 	var req request.SslConfigSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -62,6 +89,15 @@ func (s *WafSslConfigApi) GetSslConfigListApi(c *gin.Context) {
 }
 
 // DelSslConfigApi 删除SSL证书
+// @Summary      删除SSL证书
+// @Description  根据ID删除SSL证书
+// @Tags         SSL-证书配置
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "证书ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslconfig/del [get]
 func (s *WafSslConfigApi) DelSslConfigApi(c *gin.Context) {
 	var req request.SslConfigDeleteReq
 	err := c.ShouldBind(&req)
@@ -80,6 +116,15 @@ func (s *WafSslConfigApi) DelSslConfigApi(c *gin.Context) {
 }
 
 // ModifySslConfigApi 编辑SSL证书
+// @Summary      编辑SSL证书
+// @Description  修改SSL证书内容
+// @Tags         SSL-证书配置
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.SslConfigEditReq  true  "SSL证书配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslconfig/edit [post]
 func (s *WafSslConfigApi) ModifySslConfigApi(c *gin.Context) {
 	var req request.SslConfigEditReq
 	err := c.ShouldBindJSON(&req)

api/waf_sslexpire_api.go

@@ -12,6 +12,16 @@ import (
 type WafSslExpireApi struct {
 }
 
+// AddApi 新增SSL到期监控
+// @Summary      新增SSL到期监控
+// @Description  新增一个SSL证书到期监控配置
+// @Tags         SSL到期监控
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafSslExpireAddReq  true  "监控配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslexpire/add [post]
 func (w *WafSslExpireApi) AddApi(c *gin.Context) {
 	var req request.WafSslExpireAddReq
 	err := c.ShouldBindJSON(&req)
@@ -36,6 +46,16 @@ func (w *WafSslExpireApi) AddApi(c *gin.Context) {
 	}
 }
 
+// GetDetailApi 获取SSL到期监控详情
+// @Summary      获取SSL到期监控详情
+// @Description  根据ID获取SSL证书到期监控详情
+// @Tags         SSL到期监控
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslexpire/detail [get]
 func (w *WafSslExpireApi) GetDetailApi(c *gin.Context) {
 	var req request.WafSslExpireDetailReq
 	err := c.ShouldBind(&req)
@@ -47,6 +67,16 @@ func (w *WafSslExpireApi) GetDetailApi(c *gin.Context) {
 	}
 }
 
+// GetListApi 获取SSL到期监控列表
+// @Summary      获取SSL到期监控列表
+// @Description  分页查询SSL证书到期监控列表
+// @Tags         SSL到期监控
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafSslExpireSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslexpire/list [post]
 func (w *WafSslExpireApi) GetListApi(c *gin.Context) {
 	var req request.WafSslExpireSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -63,6 +93,16 @@ func (w *WafSslExpireApi) GetListApi(c *gin.Context) {
 	}
 }
 
+// DelApi 删除SSL到期监控
+// @Summary      删除SSL到期监控
+// @Description  根据ID删除SSL证书到期监控配置
+// @Tags         SSL到期监控
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "记录ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslexpire/del [get]
 func (w *WafSslExpireApi) DelApi(c *gin.Context) {
 	var req request.WafSslExpireDelReq
 	err := c.ShouldBind(&req)
@@ -80,6 +120,16 @@ func (w *WafSslExpireApi) DelApi(c *gin.Context) {
 	}
 }
 
+// ModifyApi 编辑SSL到期监控
+// @Summary      编辑SSL到期监控
+// @Description  修改SSL证书到期监控配置
+// @Tags         SSL到期监控
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafSslExpireEditReq  true  "监控配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslexpire/edit [post]
 func (w *WafSslExpireApi) ModifyApi(c *gin.Context) {
 	var req request.WafSslExpireEditReq
 	err := c.ShouldBindJSON(&req)
@@ -95,7 +145,15 @@ func (w *WafSslExpireApi) ModifyApi(c *gin.Context) {
 	}
 }
 
-// NowCheckExpireApi 现在检测过期情况
+// NowCheckExpireApi 立即检测SSL到期情况
+// @Summary      立即检测SSL到期情况
+// @Description  立即触发一次SSL证书到期检测任务
+// @Tags         SSL到期监控
+// @Accept       json
+// @Produce      json
+// @Success      200  {object}  response.Response  "发起SSL检测任务成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslexpire/nowcheck [get]
 func (w *WafSslExpireApi) NowCheckExpireApi(c *gin.Context) {
 	if global.GWAF_RUNTIME_SSL_EXPIRE_CHECK {
 		response.FailWithMessage("当前检测程序正在进行中", c)
@@ -107,7 +165,15 @@ func (w *WafSslExpireApi) NowCheckExpireApi(c *gin.Context) {
 	response.OkWithMessage("发起SSL检测任务成功", c)
 }
 
-// SyncHostApi 同步已存在主机信息
+// SyncHostApi 同步主机信息到SSL监控
+// @Summary      同步主机信息到SSL监控
+// @Description  将已配置的主机信息批量同步到SSL到期监控列表
+// @Tags         SSL到期监控
+// @Accept       json
+// @Produce      json
+// @Success      200  {object}  response.Response  "发起同步任务成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslexpire/sync_host [get]
 func (w *WafSslExpireApi) SyncHostApi(c *gin.Context) {
 	if global.GWAF_RUNTIME_SSL_SYNC_HOST {
 		response.FailWithMessage("当前正在进行中", c)

api/waf_sslorder.go

@@ -25,6 +25,16 @@ import (
 type WafSslOrderApi struct {
 }
 
+// AddApi 新建SSL证书申请订单
+// @Summary      新建SSL证书申请订单
+// @Description  向 Let's Encrypt 或 ZeroSSL 发起新的 SSL 证书申请
+// @Tags         SSL证书订单
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafSslorderaddReq  true  "订单配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslorder/add [post]
 func (w *WafSslOrderApi) AddApi(c *gin.Context) {
 	var req request.WafSslorderaddReq
 	err := c.ShouldBindJSON(&req)
@@ -78,6 +88,17 @@ func (w *WafSslOrderApi) AddApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetDetailApi 获取SSL证书订单详情
+// @Summary      获取SSL证书订单详情
+// @Description  根据ID获取SSL证书申请订单详情
+// @Tags         SSL证书订单
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "订单ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslorder/detail [get]
 func (w *WafSslOrderApi) GetDetailApi(c *gin.Context) {
 	var req request.WafSslorderdetailReq
 	err := c.ShouldBind(&req)
@@ -88,6 +109,17 @@ func (w *WafSslOrderApi) GetDetailApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetListApi 获取SSL证书订单列表
+// @Summary      获取SSL证书订单列表
+// @Description  分页查询SSL证书申请订单列表
+// @Tags         SSL证书订单
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafSslordersearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslorder/list [post]
 func (w *WafSslOrderApi) GetListApi(c *gin.Context) {
 	var req request.WafSslordersearchReq
 	err := c.ShouldBindJSON(&req)
@@ -103,6 +135,17 @@ func (w *WafSslOrderApi) GetListApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// DelApi 删除SSL证书订单
+// @Summary      删除SSL证书订单
+// @Description  根据ID删除SSL证书申请订单
+// @Tags         SSL证书订单
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "订单ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslorder/del [get]
 func (w *WafSslOrderApi) DelApi(c *gin.Context) {
 	var req request.WafSslorderdeleteReq
 	err := c.ShouldBind(&req)
@@ -121,6 +164,16 @@ func (w *WafSslOrderApi) DelApi(c *gin.Context) {
 	}
 }
 
+// ModifyApi 续期SSL证书订单
+// @Summary      续期SSL证书订单
+// @Description  对已成功申请且未过期的证书发起续期申请
+// @Tags         SSL证书订单
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafSslordereditReq  true  "续期配置"
+// @Success      200   {object}  response.Response  "续期成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/sslorder/edit [post]
 func (w *WafSslOrderApi) ModifyApi(c *gin.Context) {
 	var req request.WafSslordereditReq
 	err := c.ShouldBindJSON(&req)

api/waf_stat.go

@@ -9,23 +9,56 @@ import (
 type WafStatApi struct {
 }
 
-// 获取系统基本信息
+// StatSysinfoApi 获取首页系统基本信息
+// @Summary      获取首页系统基本信息
+// @Description  获取首页显示的系统基本信息（版本、运行状态等）
+// @Tags         统计-数据统计
+// @Produce      json
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /stat/sysinfo [get]
 func (w *WafStatApi) StatSysinfoApi(c *gin.Context) {
 
 	response.OkWithDetailed(wafStatService.StatHomeSysinfo(c), "获取成功", c)
 }
 
-// 获取运行系统基本信息
+// StatRumtimeSysinfoApi 获取运行时系统基本信息
+// @Summary      获取运行时系统基本信息
+// @Description  获取系统运行时信息（CPU、内存等）
+// @Tags         统计-数据统计
+// @Produce      json
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /stat/runtimesysinfo [get]
 func (w *WafStatApi) StatRumtimeSysinfoApi(c *gin.Context) {
 
 	response.OkWithDetailed(wafStatService.StatHomeRumtimeSysinfo(), "获取成功", c)
 }
 
+// StatHomeSumDayApi 获取今日访问统计
+// @Summary      获取今日访问统计
+// @Description  获取今日访问总量和拦截总量统计
+// @Tags         统计-数据统计
+// @Produce      json
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /stat/daytotal [get]
 func (w *WafStatApi) StatHomeSumDayApi(c *gin.Context) {
 
 	wafStat, _ := wafStatService.StatHomeSumDayApi()
 	response.OkWithDetailed(wafStat, "获取成功", c)
 }
+
+// StatHomeSumDayRangeApi 按日期范围统计访问量
+// @Summary      按日期范围统计访问量
+// @Description  按指定日期范围查询每日访问量和拦截量
+// @Tags         统计-数据统计
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafStatsDayRangeReq  true  "日期范围参数"
+// @Success      200   {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /stat/dayrangecount [post]
 func (w *WafStatApi) StatHomeSumDayRangeApi(c *gin.Context) {
 	var req request.WafStatsDayRangeReq
 	err := c.ShouldBind(&req)
@@ -37,6 +70,17 @@ func (w *WafStatApi) StatHomeSumDayRangeApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// StatHomeSumDayTopIPRangeApi 统计攻击IP排行
+// @Summary      统计攻击IP排行
+// @Description  按日期范围统计攻击IP排行（Top N）
+// @Tags         统计-数据统计
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafStatsDayRangeReq  true  "日期范围参数"
+// @Success      200   {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /stat/ipcount [post]
 func (w *WafStatApi) StatHomeSumDayTopIPRangeApi(c *gin.Context) {
 	var req request.WafStatsDayRangeReq
 	err := c.ShouldBind(&req)

api/waf_sys_log.go

@@ -9,6 +9,16 @@ import (
 type WafSysLogApi struct {
 }
 
+// GetDetailApi 获取系统日志详情
+// @Summary      获取系统日志详情
+// @Description  根据ID获取系统操作日志详情
+// @Tags         系统日志
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "日志ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /syslog/detail [get]
 func (w *WafSysLogApi) GetDetailApi(c *gin.Context) {
 	var req request.WafSysLogDetailReq
 	err := c.ShouldBind(&req)
@@ -19,6 +29,17 @@ func (w *WafSysLogApi) GetDetailApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetListApi 获取系统日志列表
+// @Summary      获取系统日志列表
+// @Description  分页查询系统操作日志列表
+// @Tags         系统日志
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafSysLogSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /syslog/list [post]
 func (w *WafSysLogApi) GetListApi(c *gin.Context) {
 	var req request.WafSysLogSearchReq
 	err := c.ShouldBind(&req)

api/waf_system_config.go

@@ -45,6 +45,17 @@ func (w *WafSystemConfigApi) GetDetailApi(c *gin.Context) {
 		response.FailWithMessage("解析失败", c)
 	}
 }
+
+// GetListApi 获取系统配置列表
+// @Summary      获取系统配置列表
+// @Description  分页查询系统配置项列表
+// @Tags         系统配置
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafSystemConfigSearchReq  true  "查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /systemconfig/list [post]
 func (w *WafSystemConfigApi) GetListApi(c *gin.Context) {
 	var req request.WafSystemConfigSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -78,6 +89,16 @@ func (w *WafSystemConfigApi) DelApi(c *gin.Context) {
 	}
 }
 
+// ModifyApi 更新系统配置
+// @Summary      更新系统配置
+// @Description  修改系统配置项的值
+// @Tags         系统配置
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafSystemConfigEditReq  true  "配置参数"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /systemconfig/edit [post]
 func (w *WafSystemConfigApi) ModifyApi(c *gin.Context) {
 	var req request.WafSystemConfigEditReq
 	err := c.ShouldBindJSON(&req)
@@ -95,7 +116,16 @@ func (w *WafSystemConfigApi) ModifyApi(c *gin.Context) {
 	}
 }
 
-// ModifyByItemApi 通过 item 修改系统配置的 value
+// ModifyByItemApi 通过item更新系统配置
+// @Summary      通过item更新系统配置
+// @Description  通过配置项的 item 键名修改对应的 value 值
+// @Tags         系统配置
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafSystemConfigEditByItemReq  true  "配置参数"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /systemconfig/updateitem [post]
 func (w *WafSystemConfigApi) ModifyByItemApi(c *gin.Context) {
 	var req request.WafSystemConfigEditByItemReq
 	err := c.ShouldBindJSON(&req)

api/waf_system_monitor.go

@@ -12,6 +12,13 @@ type WafSystemMonitorApi struct {
 var wafSystemMonitorService = waf_service.WafSystemMonitorServiceApp
 
 // GetSystemMonitorApi 获取系统监控信息
+// @Summary      获取系统监控信息
+// @Description  获取实时系统监控数据（CPU使用率、内存占用、网络流量等）
+// @Tags         系统监控
+// @Produce      json
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /monitor/info [get]
 func (w *WafSystemMonitorApi) GetSystemMonitorApi(c *gin.Context) {
 	systemInfo, err := wafSystemMonitorService.GetSystemMonitorInfo()
 	if err != nil {

api/waf_task_api.go

@@ -13,6 +13,16 @@ import (
 type WafTaskApi struct {
 }
 
+// AddApi 新增定时任务
+// @Summary      新增定时任务
+// @Description  新增一个WAF定时任务配置
+// @Tags         定时任务管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafTaskAddReq  true  "任务配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/task/add [post]
 func (w *WafTaskApi) AddApi(c *gin.Context) {
 	var req request.WafTaskAddReq
 	err := c.ShouldBindJSON(&req)
@@ -33,6 +43,16 @@ func (w *WafTaskApi) AddApi(c *gin.Context) {
 	}
 }
 
+// GetDetailApi 获取定时任务详情
+// @Summary      获取定时任务详情
+// @Description  根据ID获取定时任务详情
+// @Tags         定时任务管理
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "任务ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/task/detail [get]
 func (w *WafTaskApi) GetDetailApi(c *gin.Context) {
 	var req request.WafTaskDetailReq
 	err := c.ShouldBind(&req)
@@ -44,6 +64,16 @@ func (w *WafTaskApi) GetDetailApi(c *gin.Context) {
 	}
 }
 
+// GetListApi 获取定时任务列表
+// @Summary      获取定时任务列表
+// @Description  分页查询定时任务列表
+// @Tags         定时任务管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafTaskSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/task/list [post]
 func (w *WafTaskApi) GetListApi(c *gin.Context) {
 	var req request.WafTaskSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -60,6 +90,16 @@ func (w *WafTaskApi) GetListApi(c *gin.Context) {
 	}
 }
 
+// DelApi 删除定时任务
+// @Summary      删除定时任务
+// @Description  根据ID删除定时任务配置
+// @Tags         定时任务管理
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "任务ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/task/del [get]
 func (w *WafTaskApi) DelApi(c *gin.Context) {
 	var req request.WafTaskDelReq
 	err := c.ShouldBind(&req)
@@ -77,6 +117,16 @@ func (w *WafTaskApi) DelApi(c *gin.Context) {
 	}
 }
 
+// ModifyApi 编辑定时任务
+// @Summary      编辑定时任务
+// @Description  修改定时任务配置并重新调度
+// @Tags         定时任务管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafTaskEditReq  true  "任务配置"
+// @Success      200   {object}  response.Response  "编辑成功，任务已重新调度"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/task/edit [post]
 func (w *WafTaskApi) ModifyApi(c *gin.Context) {
 	var req request.WafTaskEditReq
 	err := c.ShouldBindJSON(&req)
@@ -101,6 +151,16 @@ func (w *WafTaskApi) ModifyApi(c *gin.Context) {
 	}
 }
 
+// ManualExecuteApi 手动执行定时任务
+// @Summary      手动执行定时任务
+// @Description  根据ID立即手动触发执行一次定时任务
+// @Tags         定时任务管理
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "任务ID"
+// @Success      200  {object}  response.Response  "发起成功"
+// @Security     ApiKeyAuth
+// @Router       /wafhost/task/manual_exec [get]
 func (w *WafTaskApi) ManualExecuteApi(c *gin.Context) {
 	var req request.WafTaskDetailReq
 	err := c.ShouldBind(&req)

api/waf_tunnel_api.go

@@ -21,6 +21,16 @@ import (
 type WafTunnelApi struct {
 }
 
+// AddApi 新增隧道配置
+// @Summary      新增隧道配置
+// @Description  新增一个TCP/UDP端口转发隧道配置
+// @Tags         隧道管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafTunnelAddReq  true  "隧道配置"
+// @Success      200   {object}  response.Response  "添加成功"
+// @Security     ApiKeyAuth
+// @Router       /tunnel/tunnel/add [post]
 func (w *WafTunnelApi) AddApi(c *gin.Context) {
 	var req request.WafTunnelAddReq
 	err := c.ShouldBindJSON(&req)
@@ -89,6 +99,16 @@ func (w *WafTunnelApi) AddApi(c *gin.Context) {
 	}
 }
 
+// GetDetailApi 获取隧道配置详情
+// @Summary      获取隧道配置详情
+// @Description  根据ID获取隧道配置详情
+// @Tags         隧道管理
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "隧道ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /tunnel/tunnel/detail [get]
 func (w *WafTunnelApi) GetDetailApi(c *gin.Context) {
 	var req request.WafTunnelDetailReq
 	err := c.ShouldBind(&req)
@@ -100,6 +120,16 @@ func (w *WafTunnelApi) GetDetailApi(c *gin.Context) {
 	}
 }
 
+// GetListApi 获取隧道配置列表
+// @Summary      获取隧道配置列表
+// @Description  分页查询隧道配置列表
+// @Tags         隧道管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafTunnelSearchReq  true  "分页查询参数"
+// @Success      200   {object}  response.Response{data=response.PageResult}  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /tunnel/tunnel/list [post]
 func (w *WafTunnelApi) GetListApi(c *gin.Context) {
 	var req request.WafTunnelSearchReq
 	err := c.ShouldBindJSON(&req)
@@ -116,6 +146,16 @@ func (w *WafTunnelApi) GetListApi(c *gin.Context) {
 	}
 }
 
+// DelApi 删除隧道配置
+// @Summary      删除隧道配置
+// @Description  根据ID删除隧道配置并关闭对应端口监听
+// @Tags         隧道管理
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "隧道ID"
+// @Success      200  {object}  response.Response  "删除成功"
+// @Security     ApiKeyAuth
+// @Router       /tunnel/tunnel/del [get]
 func (w *WafTunnelApi) DelApi(c *gin.Context) {
 	var req request.WafTunnelDelReq
 	err := c.ShouldBind(&req)
@@ -141,6 +181,16 @@ func (w *WafTunnelApi) DelApi(c *gin.Context) {
 	}
 }
 
+// ModifyApi 编辑隧道配置
+// @Summary      编辑隧道配置
+// @Description  修改隧道配置并重新启动转发
+// @Tags         隧道管理
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafTunnelEditReq  true  "隧道配置"
+// @Success      200   {object}  response.Response  "编辑成功"
+// @Security     ApiKeyAuth
+// @Router       /tunnel/tunnel/edit [post]
 func (w *WafTunnelApi) ModifyApi(c *gin.Context) {
 	var req request.WafTunnelEditReq
 	err := c.ShouldBindJSON(&req)
@@ -167,7 +217,16 @@ func (w *WafTunnelApi) ModifyApi(c *gin.Context) {
 	}
 }
 
-// GetTunnelConnectionsApi 获取隧道连接信息API
+// GetTunnelConnectionsApi 获取隧道实时连接信息
+// @Summary      获取隧道实时连接信息
+// @Description  获取指定隧道的实时 TCP/UDP 连接数及来源 IP 列表
+// @Tags         隧道管理
+// @Accept       json
+// @Produce      json
+// @Param        id  query     string  true  "隧道ID"
+// @Success      200  {object}  response.Response  "获取成功"
+// @Security     ApiKeyAuth
+// @Router       /tunnel/tunnel/connections [get]
 func (w *WafTunnelApi) GetTunnelConnectionsApi(c *gin.Context) {
 	var req request.WafTunnelConnReq
 	err := c.ShouldBind(&req)

api/waf_vpconfig_api.go

@@ -21,7 +21,16 @@ import (
 type WafVpConfigApi struct {
 }
 
-// UpdateIpWhitelistApi 更新IP白名单配置
+// UpdateIpWhitelistApi 更新管理端IP白名单
+// @Summary      更新管理端IP白名单
+// @Description  更新管理端允许访问的IP白名单（CIDR格式，多个用逗号分隔）
+// @Tags         管理端配置
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafVpConfigIpWhitelistUpdateReq  true  "IP白名单配置"
+// @Success      200   {object}  response.Response  "更新IP白名单成功"
+// @Security     ApiKeyAuth
+// @Router       /vipconfig/updateIpWhitelist [post]
 func (w *WafVpConfigApi) UpdateIpWhitelistApi(c *gin.Context) {
 	var req request.WafVpConfigIpWhitelistUpdateReq
 	err := c.ShouldBindJSON(&req)
@@ -39,7 +48,15 @@ func (w *WafVpConfigApi) UpdateIpWhitelistApi(c *gin.Context) {
 	}
 }
 
-// GetIpWhitelistApi 获取IP白名单配置
+// GetIpWhitelistApi 获取管理端IP白名单
+// @Summary      获取管理端IP白名单
+// @Description  获取当前管理端允许访问的IP白名单配置
+// @Tags         管理端配置
+// @Accept       json
+// @Produce      json
+// @Success      200  {object}  response.Response  "获取IP白名单成功"
+// @Security     ApiKeyAuth
+// @Router       /vipconfig/getIpWhitelist [get]
 func (w *WafVpConfigApi) GetIpWhitelistApi(c *gin.Context) {
 	// 直接从全局变量获取IP白名单
 	ipWhitelist := global.GWAF_IP_WHITELIST
@@ -52,7 +69,16 @@ func (w *WafVpConfigApi) GetIpWhitelistApi(c *gin.Context) {
 	response.OkWithDetailed(resp, "获取IP白名单成功", c)
 }
 
-// UpdateSslEnableApi 更新SSL启用状态
+// UpdateSslEnableApi 更新管理端SSL启用状态
+// @Summary      更新管理端SSL启用状态
+// @Description  开启或关闭管理端HTTPS，修改后需重启管理端生效
+// @Tags         管理端配置
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafVpConfigSslEnableUpdateReq  true  "SSL启用配置"
+// @Success      200   {object}  response.Response  "更新SSL启用状态成功"
+// @Security     ApiKeyAuth
+// @Router       /vipconfig/updateSslEnable [post]
 func (w *WafVpConfigApi) UpdateSslEnableApi(c *gin.Context) {
 	var req request.WafVpConfigSslEnableUpdateReq
 	err := c.ShouldBindJSON(&req)
@@ -69,7 +95,15 @@ func (w *WafVpConfigApi) UpdateSslEnableApi(c *gin.Context) {
 	}
 }
 
-// GetSslStatusApi 获取SSL状态
+// GetSslStatusApi 获取管理端SSL状态
+// @Summary      获取管理端SSL状态
+// @Description  获取管理端SSL启用状态及证书信息（证书内容、域名、到期时间）
+// @Tags         管理端配置
+// @Accept       json
+// @Produce      json
+// @Success      200  {object}  response.Response  "获取SSL状态成功"
+// @Security     ApiKeyAuth
+// @Router       /vipconfig/getSslStatus [get]
 func (w *WafVpConfigApi) GetSslStatusApi(c *gin.Context) {
 	// 获取SSL启用状态
 	sslEnable := global.GWAF_SSL_ENABLE
@@ -118,7 +152,16 @@ func (w *WafVpConfigApi) GetSslStatusApi(c *gin.Context) {
 	response.OkWithDetailed(resp, "获取SSL状态成功", c)
 }
 
-// UploadSslCertApi 上传SSL证书
+// UploadSslCertApi 上传管理端SSL证书
+// @Summary      上传管理端SSL证书
+// @Description  上传PEM格式的证书和私钥，校验通过后保存到 data/ssl/manager 目录，需重启生效
+// @Tags         管理端配置
+// @Accept       json
+// @Produce      json
+// @Param        data  body      request.WafVpConfigSslUploadReq  true  "证书配置"
+// @Success      200   {object}  response.Response  "上传SSL证书成功"
+// @Security     ApiKeyAuth
+// @Router       /vipconfig/uploadSslCert [post]
 func (w *WafVpConfigApi) UploadSslCertApi(c *gin.Context) {
 	var req request.WafVpConfigSslUploadReq
 	err := c.ShouldBindJSON(&req)
@@ -274,6 +317,14 @@ func getCertInfo(certPath string) CertInfo {
 }
 
 // RestartManagerApi 重启管理端
+// @Summary      重启管理端
+// @Description  触发管理端1秒后重启，请等待5-10秒后重新访问
+// @Tags         管理端配置
+// @Accept       json
+// @Produce      json
+// @Success      200  {object}  response.Response  "管理端将在1秒后重启"
+// @Security     ApiKeyAuth
+// @Router       /vipconfig/restartManager [post]
 func (w *WafVpConfigApi) RestartManagerApi(c *gin.Context) {
 	response.OkWithMessage("管理端将在1秒后重启，请稍候5-10秒后重新访问", c)
 

gen_swagger.bat

@@ -0,0 +1,54 @@
+@echo off
+chcp 65001 >nul
+echo ============================================
+echo  SamWaf Swagger 文档生成脚本
+echo ============================================
+echo.
+
+:: 切换到脚本所在目录（项目根目录）
+cd /d "%~dp0"
+
+:: 查找 swag.exe 路径（优先 GOPATH/bin，其次 PATH）
+set SWAG_EXE=
+if exist "%GOPATH%\bin\swag.exe" (
+    set SWAG_EXE=%GOPATH%\bin\swag.exe
+) else if exist "%USERPROFILE%\go\bin\swag.exe" (
+    set SWAG_EXE=%USERPROFILE%\go\bin\swag.exe
+) else (
+    where swag >nul 2>&1
+    if %errorlevel% == 0 (
+        set SWAG_EXE=swag
+    )
+)
+
+if "%SWAG_EXE%"=="" (
+    echo [错误] 未找到 swag.exe，请先执行以下命令安装：
+    echo   go install github.com/swaggo/swag/cmd/swag@latest
+    echo.
+    pause
+    exit /b 1
+)
+
+echo [信息] 使用 swag: %SWAG_EXE%
+echo [信息] 开始生成 Swagger 文档...
+echo.
+
+"%SWAG_EXE%" init ^
+    -g cmd/samwaf/main.go ^
+    -o docs/openapi ^
+    --parseDependency ^
+    --parseInternal
+
+if %errorlevel% == 0 (
+    echo.
+    echo [成功] Swagger 文档已生成至 docs/openapi/
+    echo   - docs/openapi/docs.go
+    echo   - docs/openapi/swagger.json
+    echo   - docs/openapi/swagger.yaml
+) else (
+    echo.
+    echo [失败] 文档生成过程中出现错误，请检查上方日志
+)
+
+echo.
+pause

middleware/auth_api_check.go

@@ -19,6 +19,20 @@ var (
 	wafOtpService       = waf_service.WafOtpServiceApp
 )
 
+// TokenOnlyAuth 仅允许后台 Token 登录访问，拒绝 OpenAPI Key 方式
+// 用于保护「开放平台管理」类接口（Key管理、调用日志、API文档），防止通过 API Key 自行操作
+func TokenOnlyAuth() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if c.GetHeader("X-API-Key") != "" {
+			response.AuthFailWithMessage("该接口不允许通过 API Key 访问，请使用后台账号登录", c)
+			c.Abort()
+			return
+		}
+		// 复用 Token 校验逻辑
+		Auth()(c)
+	}
+}
+
 // Auth 鉴权中间件
 func Auth() gin.HandlerFunc {
 	innerName := "Auth"

wafmangeweb/localserver.go

@@ -56,7 +56,6 @@ func (web *WafWebManager) initRouter(r *gin.Engine) {
 		router.ApiGroupApp.InitIPFailureRouter(RouterGroup)
 		router.ApiGroupApp.InitBlockIpRouter(RouterGroup)
 		router.ApiGroupApp.InitBlockUrlRouter(RouterGroup)
-		router.ApiGroupApp.InitAccountRouter(RouterGroup)
 		router.ApiGroupApp.InitAccountLogRouter(RouterGroup)
 		router.ApiGroupApp.InitLoginOutRouter(RouterGroup)
 		router.ApiGroupApp.InitSysLogRouter(RouterGroup)
@@ -77,7 +76,6 @@ func (web *WafWebManager) initRouter(r *gin.Engine) {
 		router.ApiGroupApp.InitWafTaskRouter(RouterGroup)
 		router.ApiGroupApp.InitWafBlockingPageRouter(RouterGroup)
 		router.ApiGroupApp.InitGPTRouter(RouterGroup)
-		router.ApiGroupApp.InitWafOtpRouter(RouterGroup)
 		router.ApiGroupApp.InitAnalysisRouter(RouterGroup)
 		router.ApiGroupApp.InitWafPrivateInfoRouter(RouterGroup)
 		router.ApiGroupApp.InitWafPrivateGroupRouter(RouterGroup)
@@ -87,16 +85,28 @@ func (web *WafWebManager) initRouter(r *gin.Engine) {
 		router.ApiGroupApp.InitWafFileRouter(RouterGroup)
 		router.ApiGroupApp.InitWafSystemMonitorRouter(RouterGroup)
 		router.ApiGroupApp.InitWafCaServerInfoRouter(RouterGroup)
-		router.ApiGroupApp.InitSqlQueryRouter(RouterGroup)
 		router.ApiGroupApp.InitNotifyChannelRouter(RouterGroup)
 		router.ApiGroupApp.InitNotifySubscriptionRouter(RouterGroup)
 		router.ApiGroupApp.InitNotifyLogRouter(RouterGroup)
 		router.ApiGroupApp.InitFirewallIPBlockRouter(RouterGroup)
 		router.ApiGroupApp.InitLogFileWriteRouter(RouterGroup)
 		router.ApiGroupApp.InitIPLocationRouter(RouterGroup)
-		router.ApiGroupApp.InitOPlatformKeyRouter(RouterGroup)
-		router.ApiGroupApp.InitOPlatformLogRouter(RouterGroup)
-		router.ApiGroupApp.InitOPlatformDocRouter(RouterGroup)
+	}
+
+	// 仅允许后台 Token 登录访问，拒绝 API Key 访问（安全敏感接口）
+	TokenOnlyRouterGroup := r.Group("")
+	TokenOnlyRouterGroup.Use(middleware.TokenOnlyAuth(), middleware.CenterApi(), middleware.SecApi(), middleware.GinGlobalExceptionMiddleWare(), middleware.IPWhitelist())
+	{
+		// 开放平台管理接口
+		router.ApiGroupApp.InitOPlatformKeyRouter(TokenOnlyRouterGroup)
+		router.ApiGroupApp.InitOPlatformLogRouter(TokenOnlyRouterGroup)
+		router.ApiGroupApp.InitOPlatformDocRouter(TokenOnlyRouterGroup)
+		// 账号管理：防止通过 API Key 删除/修改管理员账号
+		router.ApiGroupApp.InitAccountRouter(TokenOnlyRouterGroup)
+		// OTP 双因素认证管理：安全配置类接口
+		router.ApiGroupApp.InitWafOtpRouter(TokenOnlyRouterGroup)
+		// SQL 查询：直接执行数据库查询，极度敏感
+		router.ApiGroupApp.InitSqlQueryRouter(TokenOnlyRouterGroup)
 	}
 
 	// 保存 gin.Engine 引用供 API 文档生成使用