Golang 项目中使用 Swagger

在日常的 Go 项目开发中，接口文档的维护往往是一件麻烦事。手动写文档不仅费时，还容易和实际代码脱节。Swagger 提供了一种优雅的解决方案：通过注解自动生成接口文档，并且可以在 Swagger UI 中直接调试接口。

本文将结合实际代码，介绍如何在 Golang 项目中集成 Swagger，并详细说明常见注解的用法。

一、初始化 Swagger 文档

首先安装 swag 工具：

bash 复制代码

go install github.com/swaggo/swag/cmd/swag@latest

在项目根目录执行：

bash 复制代码

# 在当前目录 docs 文件夹生成 docs.go、swagger.json、swagger.yaml 三个文件
swag init -g ./cmd/server/main.go

这样就会在 docs 文件夹下生成 Swagger 文档相关文件。

二、项目中集成 Swagger

在 server 层中注册 Swagger 路由：

go 复制代码

// swagger doc
docs.SwaggerInfo.BasePath = "/v1"
s.GET("/swagger/*any", ginSwagger.WrapHandler(
  swaggerfiles.Handler,
  ginSwagger.DefaultModelsExpandDepth(-1),
  ginSwagger.PersistAuthorization(true),
))

在 model 层定义请求参数时，可以通过 example 提供示例值，方便前端在 Swagger UI 中测试：

go 复制代码

type RegisterRequest struct {
  Email    string `json:"email" binding:"required" example:"1234@gmail.com"`
  Password string `json:"password" binding:"required" example:"123456"`
}

在 handler 层为接口添加注解：

go 复制代码

// Register godoc
// @Summary 用户注册
// @Description 目前只支持邮箱登录
// @Tags 用户模块
// @Accept json
// @Produce json
// @Param request body v1.RegisterRequest true "params"
// @Success 200 {object} v1.Response
// @Router /register [post]
func (h *UserHandler) Register(ctx *gin.Context) {
    // 业务逻辑省略
}

三、常见 Swagger 注解说明

注解	作用	示例
`@Summary`	接口简要说明	`// @Summary 获取用户信息`
`@Description`	接口详细描述	`// @Description 根据用户ID获取用户详细信息`
`@Tags`	接口分类	`// @Tags 用户管理, 基础功能`
`@Accept`	接收的请求类型	`// @Accept application/json`
`@Produce`	返回的响应类型	`// @Produce application/json`
`@Param`	请求参数说明	`// @Param id path int true "用户ID"`
`@Success`	成功响应	`// @Success 200 {object} model.User "用户信息"`
`@Failure`	失败响应	`// @Failure 404 {object} errcode.Error "用户不存在"`
`@Router`	路由与方法	`// @Router /users/{id} [GET]`
`@Deprecated`	标记接口废弃	`// @Deprecated`
`@Since`	标记接口版本	`// @Since v1.0.0`

四、@Param 的扩展用法

@Param 支持更多属性，例如：

go 复制代码

// @Param page query int false "页码" default(1) min(1)
// @Param status query string false "状态" enum(active,inactive)

default：默认值
enum：枚举值
min/max：数值范围
format：格式（如 date-time）

五、完整示例

go 复制代码

// @Summary 获取用户信息
// @Description 根据用户ID获取用户详细信息
// @Tags 用户管理
// @Produce application/json
// @Param id path int true "用户ID"
// @Success 200 {object} model.User "用户信息"
// @Failure 404 {object} errcode.Error "用户不存在"
// @Router /users/{id} [GET]
func GetUser(c *gin.Context) {
    // 实现逻辑
}

六、常见问题 FAQ

Q1：Swagger UI 无法访问怎么办？

检查是否正确注册了路由，例如：

go 复制代码

r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))

然后访问 http://localhost:8080/swagger/index.html。

Q2：如何自定义文档标题和描述？

在 docs/docs.go 中修改 SwaggerInfo：

go 复制代码

docs.SwaggerInfo.Title = "我的项目 API 文档"
docs.SwaggerInfo.Description = "这是一个示例项目的接口文档"
docs.SwaggerInfo.Version = "1.0"

Q3：修改注解后文档没有更新？

需要重新执行：

bash 复制代码

swag init -g ./cmd/server/main.go

Q4：如何隐藏某些接口？

在注释中添加：

go 复制代码

// @Router /internal [get]
// @Summary 内部接口
// @Hidden

七、注意事项

@Param 的参数顺序必须严格遵循：name in type required description。
结构体字段必须导出（首字母大写），否则 Swagger 无法解析。
不同工具（如 swaggo、go-swagger）对注解支持略有差异，需参考对应文档。
每次修改注解后，需要重新执行 swag init 生成文档。

八、总结

通过合理使用 Swagger 注解，可以让 Go 项目的接口文档 自动化生成，不仅减少了手动维护的成本，还能在 Swagger UI 中直接调试接口，极大提升开发效率。

如果你正在做一个中大型项目，强烈建议在项目初期就集成 Swagger，这样后续的接口协作和维护会轻松很多。