feat(server): 集成 Swagger API 文档

- 引入 swaggo/gin-swagger 和 swaggo/files 依赖 - 配置 Swagger UI 路由 /swagger/* - 为测试 handler 函数添加 Swagger 注解 - 将 main.go 中的内联 handler 重构到 handler/test.go 以支持注解 - 生成 Swagger 文档 (docs.go, swagger.json, swagger.yaml) - Makefile 新增 make swagger 命令 - .gitignore 添加 server/docs/ 以跟踪生成的文档 - 添加 API 元信息（标题、版本、联系方式、许可证、安全定义）
2026-07-15 11:33:00 +08:00
parent 659ff617a4
commit 8898437e9e
9 changed files with 1200 additions and 49 deletions
@@ -0,0 +1,125 @@
+package handler
+
+import (
+	"fmt"
+	"net/http"
+	"strconv"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+// Ping 健康检查
+// @Summary      健康检查
+// @Description  检查服务器是否正常运行
+// @Tags         系统
+// @Accept       json
+// @Produce      json
+// @Success      200  {object}  Response{data=object{time=string}}
+// @Router       /ping [get]
+func Ping(c *gin.Context) {
+	Success(c, gin.H{"time": time.Now().Format(time.RFC3339)})
+}
+
+// TestSuccess 测试成功响应
+// @Summary      测试成功响应
+// @Description  测试返回成功的统一响应格式
+// @Tags         测试
+// @Accept       json
+// @Produce      json
+// @Success      200  {object}  Response{data=object{username=string,role=string}}
+// @Router       /test/success [get]
+func TestSuccess(c *gin.Context) {
+	Success(c, gin.H{
+		"username": "testuser",
+		"role":     "admin",
+	})
+}
+
+// TestError 测试业务错误响应
+// @Summary      测试业务错误响应
+// @Description  根据错误码返回对应的业务错误响应
+// @Tags         测试
+// @Accept       json
+// @Produce      json
+// @Param        code   path      int  true  "业务错误码 (10001-10099: 认证相关, 20001-20099: 任务相关)"
+// @Success      200    {object}  Response{details=string}
+// @Failure      400    {object}  Response
+// @Router       /test/error/{code} [get]
+func TestError(c *gin.Context) {
+	codeStr := c.Param("code")
+	code, err := strconv.Atoi(codeStr)
+	if err != nil {
+		BadRequest(c, "错误码必须是数字")
+		return
+	}
+	details := fmt.Sprintf("这是错误码 %d 的测试响应", code)
+	Error(c, http.StatusOK, code, details)
+}
+
+// Test500 测试 500 错误
+// @Summary      测试 500 错误
+// @Description  模拟返回 HTTP 500 服务器内部错误
+// @Tags         测试
+// @Accept       json
+// @Produce      json
+// @Success      500  {object}  Response
+// @Router       /test/500 [get]
+func Test500(c *gin.Context) {
+	InternalError(c, "模拟服务器内部错误")
+}
+
+// Test401 测试 401 错误
+// @Summary      测试 401 错误
+// @Description  模拟返回 HTTP 401 未授权错误
+// @Tags         测试
+// @Accept       json
+// @Produce      json
+// @Success      401  {object}  Response
+// @Router       /test/401 [get]
+func Test401(c *gin.Context) {
+	Unauthorized(c, "模拟 Token 过期")
+}
+
+// Test403 测试 403 错误
+// @Summary      测试 403 错误
+// @Description  模拟返回 HTTP 403 禁止访问错误
+// @Tags         测试
+// @Accept       json
+// @Produce      json
+// @Success      403  {object}  Response
+// @Router       /test/403 [get]
+func Test403(c *gin.Context) {
+Forbidden(c, "模拟无权限")
+}
+
+// TestTimeout 测试超时响应
+// @Summary      测试超时响应
+// @Description  模拟请求超时（15秒延迟，超过前端 10s timeout）
+// @Tags         测试
+// @Accept       json
+// @Produce      json
+// @Success      200  {object}  Response
+// @Failure      408  {object}  Response
+// @Router       /test/timeout [get]
+func TestTimeout(c *gin.Context) {
+	time.Sleep(15 * time.Second)
+	Success(c, "这条消息不应该出现")
+}
+
+// TestPaginated 测试分页响应
+// @Summary      测试分页响应
+// @Description  测试返回分页数据的统一响应格式
+// @Tags         测试
+// @Accept       json
+// @Produce      json
+// @Success      200  {object}  Response{data=PaginatedData{items=[]object}}
+// @Router       /test/paginated [get]
+func TestPaginated(c *gin.Context) {
+	items := []gin.H{
+		{"id": 1, "name": "item-1"},
+		{"id": 2, "name": "item-2"},
+		{"id": 3, "name": "item-3"},
+	}
+	SuccessWithPaginated(c, 100, items)
+}