Golang 项目中使用 Swagger
Golang 项目中使用 Swagger
在日常的 Go 项目开发中，接口文档的维护往往是一件麻烦事。手动写文档不仅费时，还容易和实际代码脱节。Swagger 提供了一种优雅的解决方案：通过注解自动生成接口文档，并且可以在 Swagger UI 中直接调试接口。
本文将结合实际代码，介绍如何在 Golang 项目中集成 Swagger，并详细说明常见注解的用法。
一、初始化 Swagger 文档
首先安装 swag 工具：
go install github.com/swaggo/swag/cmd/swag@latest
在项目根目录执行：
# 在当前目录 docs 文件夹生成 docs.go、swagger.json、swagger.yaml 三个文件
swag init -g ./cmd/server/main.go
这样就会在 docs 文件夹下生成 Swagger 文档相关文件。
二、项目中集成 Swagger
在 server 层中注册 Swagger 路由：
// swagger doc
docs.SwaggerInfo.BasePath = "/v1"
s.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler,ginSwagger.DefaultModelsExpandDepth(-1),ginSwagger.PersistAuthorization(true),
))
在 model 层定义请求参数时，可以通过 example 提供示例值，方便前端在 Swagger UI 中测试：
type RegisterRequest struct {Email string `json:"email" binding:"required" example:"1234@gmail.com"`Password string `json:"password" binding:"required" example:"123456"`
}
在 handler 层为接口添加注解：
// 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 支持更多属性，例如：
// @Param page query int false "页码" default(1) min(1)
// @Param status query string false "状态" enum(active,inactive)
default：默认值enum：枚举值min/max：数值范围format：格式（如date-time）
五、完整示例
// @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 无法访问怎么办？
检查是否正确注册了路由，例如：
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
然后访问 http://localhost:8080/swagger/index.html。
Q2：如何自定义文档标题和描述？
在 docs/docs.go 中修改 SwaggerInfo：
docs.SwaggerInfo.Title = "我的项目 API 文档"
docs.SwaggerInfo.Description = "这是一个示例项目的接口文档"
docs.SwaggerInfo.Version = "1.0"
Q3：修改注解后文档没有更新？
需要重新执行：
swag init -g ./cmd/server/main.go
Q4：如何隐藏某些接口？
在注释中添加：
// @Router /internal [get]
// @Summary 内部接口
// @Hidden
七、注意事项
@Param的参数顺序必须严格遵循：name in type required description。- 结构体字段必须导出（首字母大写），否则 Swagger 无法解析。
- 不同工具（如
swaggo、go-swagger）对注解支持略有差异，需参考对应文档。 - 每次修改注解后，需要重新执行
swag init生成文档。
八、总结
通过合理使用 Swagger 注解，可以让 Go 项目的接口文档 自动化生成，不仅减少了手动维护的成本，还能在 Swagger UI 中直接调试接口，极大提升开发效率。
如果你正在做一个中大型项目，强烈建议在项目初期就集成 Swagger，这样后续的接口协作和维护会轻松很多。