swagger

internal/app/api/api.go

@@ -8,10 +8,14 @@ import (
 
 	"git.huangwc.com/pig/pig-farm-controller/internal/app/controller/user"
 	"git.huangwc.com/pig/pig-farm-controller/internal/app/service/token"
-	"git.huangwc.com/pig/pig-farm-controller/internal/infra/config" // 引入 config 包
+	"git.huangwc.com/pig/pig-farm-controller/internal/infra/config"
 	"git.huangwc.com/pig/pig-farm-controller/internal/infra/logs"
 	"git.huangwc.com/pig/pig-farm-controller/internal/infra/repository"
 	"github.com/gin-gonic/gin"
+
+	_ "git.huangwc.com/pig/pig-farm-controller/docs" // 引入 swag 生成的 docs
+	swaggerFiles "github.com/swaggo/files"
+	ginSwagger "github.com/swaggo/gin-swagger"
 )
 
 // API 结构体定义了 HTTP 服务器及其依赖
@@ -68,6 +72,10 @@ func (a *API) setupRoutes() {
 			userGroup.POST("/login", a.userController.Login) // 注册用户登录接口 (POST /api/v1/users/login)
 		}
 	}
+
+	// 添加 Swagger UI 路由
+	a.engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
+	a.logger.Info("Swagger UI is available at /swagger/index.html")
 }
 
 // Start 启动 HTTP 服务器
@@ -88,7 +96,7 @@ func (a *API) Start() {
 	go func() {
 		// 启动服务器，并检查错误。http.ErrServerClosed 是正常关闭时的错误，无需处理。
 		if err := a.httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-			a.logger.Fatalf("HTTP 服务器监听失败: %s", err) // 如果是其他错误，则记录致命错误并退出
+			a.logger.Fatalf("HTTP 服务器监听失败: %s", err)
 		}
 	}()
 	// 记录服务器已启动的信息

internal/app/controller/user/user_controller.go

@@ -30,30 +30,41 @@ func NewController(userRepo repository.UserRepository, logger *logs.Logger, toke
 
 // CreateUserRequest 定义创建用户请求的结构体
 type CreateUserRequest struct {
-	Username string `json:"username" binding:"required"`
-	Password string `json:"password" binding:"required,min=6"`
+	Username string `json:"username" binding:"required" example:"newuser"`
+	Password string `json:"password" binding:"required,min=6" example:"password123"`
 }
 
 // LoginRequest 定义登录请求的结构体
 type LoginRequest struct {
-	Username string `json:"username" binding:"required"`
-	Password string `json:"password" binding:"required"`
+	Username string `json:"username" binding:"required" example:"testuser"`
+	Password string `json:"password" binding:"required" example:"password123"`
 }
 
 // CreateUserResponse 定义创建用户成功响应的结构体
 type CreateUserResponse struct {
-	Username string `json:"username"`
-	ID       uint   `json:"id"`
+	Username string `json:"username" example:"newuser"`
+	ID       uint   `json:"id" example:"1"`
 }
 
 // LoginResponse 定义登录成功响应的结构体
 type LoginResponse struct {
-	Username string `json:"username"`
-	ID       uint   `json:"id"`
-	Token    string `json:"token"`
+	Username string `json:"username" example:"testuser"`
+	ID       uint   `json:"id" example:"1"`
+	Token    string `json:"token" example:"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."`
 }
 
-// CreateUser 处理创建用户的请求
+// CreateUser godoc
+// @Summary      创建新用户
+// @Description  根据用户名和密码创建一个新的系统用户。
+// @Tags         用户管理
+// @Accept       json
+// @Produce      json
+// @Param        user body CreateUserRequest true "用户信息"
+// @Success      200 {object} controller.Response{data=CreateUserResponse} "用户创建成功"
+// @Failure      400 {object} controller.Response "请求参数错误"
+// @Failure      409 {object} controller.Response "用户名已存在"
+// @Failure      500 {object} controller.Response "服务器内部错误"
+// @Router       /users [post]
 func (c *Controller) CreateUser(ctx *gin.Context) {
 	var req CreateUserRequest
 	if err := ctx.ShouldBindJSON(&req); err != nil {
@@ -88,7 +99,18 @@ func (c *Controller) CreateUser(ctx *gin.Context) {
 	})
 }
 
-// Login 处理用户登录请求
+// Login godoc
+// @Summary      用户登录
+// @Description  用户使用用户名和密码登录，成功后返回 JWT 令牌。
+// @Tags         用户管理
+// @Accept       json
+// @Produce      json
+// @Param        credentials body LoginRequest true "登录凭证"
+// @Success      200 {object} controller.Response{data=LoginResponse} "登录成功"
+// @Failure      400 {object} controller.Response "请求参数错误"
+// @Failure      401 {object} controller.Response "用户名或密码不正确"
+// @Failure      500 {object} controller.Response "服务器内部错误"
+// @Router       /users/login [post]
 func (c *Controller) Login(ctx *gin.Context) {
 	var req LoginRequest
 	if err := ctx.ShouldBindJSON(&req); err != nil {