如何在 Go 中使用 Swagger 自动生成微服务的 API 接口文档

swag 更适合已有 Go 微服务快速补文档。它基于代码注释生成 OpenAPI 3.0，侵入少、适配 Gin/Echo/Chi 等框架快；go-swagger 则需先写 spec 再生成代码，适合契约先行场景。

Swagger 生成器选哪个：swag 还是 go-swagger？

Go 生态里主流的 Swagger 文档生成工具就两个：swag 和 go-swagger，但它们思路完全不同。swag 是基于代码注释生成 OpenAPI 3.0 文档，轻量、侵入少、适配 Gin/Echo/Chi 等框架快；go-swagger 是从 OpenAPI spec 文件（yaml/json）反向生成 Go 代码，适合“契约先行”流程，但对已有微服务改造成本高。

如果你的微服务已经用 Gin 或标准 http.ServeMux 写好了 handler，想快速补文档，swag 是更现实的选择。它不改业务逻辑，只加几行注释，再跑一条命令就能生成 docs/docs.go，直接嵌入服务启动流程。

• swag init -g cmd/main.go -o ./docs：必须指定入口文件（含 main()），否则扫描不到路由
• 注释必须紧贴 handler 函数声明上方，不能隔空行，否则解析失败
• @Summary 和 @Produce 是必填项，缺一个 swag init 就报错退出

注释怎么写才被 swag 正确识别？

Swag 不解析代码逻辑，只靠特定格式的注释块提取元数据。每个 handler 对应一个 // @... 块，顺序不重要，但字段名必须拼写准确、大小写敏感。

常见漏掉或写错的点：

• @Param 的类型写成 query 却漏了 in: query，实际会被忽略
• @Success 200 {object} model.User 中的 model.User 必须是可导出结构体（首字母大写），且包路径要和 import 一致
• 如果 handler 返回 error，别忘了加 @Failure 400 {string} string "Bad Request"，否则生成的文档里看不到错误响应示例
• 数组响应要写成 @Success 200 {array} model.User，不是 {object} []model.User

示例片段：

// @Summary 获取用户详情
// @Description 根据 ID 查询用户信息
// @ID get-user-by-id
// @Produce json
// @Param id path int true "用户ID"
// @Success 200 {object} model.User
// @Failure 404 {string} string "Not Found"
// @Router /users/{id} [get]
func GetUserHandler(w http.ResponseWriter, r *http.Request) { ... }

如何把生成的文档页面集成进微服务？

生成的 docs/docs.go 是个内嵌静态资源文件，本质是把 Swagger UI 的 HTML/JS/CSS 打包进了 Go 二进制。集成只需两步：注册路由 + 启动时调用初始化函数。

• 在 main() 开头加 docs.SwaggerInfo.Title = "User Service"，不然页面标题默认是 “Swagger API”
• Gin 用户用 ginSwagger.WrapHandler(docs.Handler)；标准 net/http 用 http.Handle("/swagger/", http.StripPrefix("/swagger/", docs.Handler))
• 别把 Swagger 路由放在中间件之后（比如 JWT 验证中间件），否则未登录用户打不开文档页——除非你真想限制访问
• 生产环境建议关掉，或加 IP 白名单，因为 /swagger/* 路径会暴露所有接口定义

为什么本地能跑，K8s 里点开空白？

常见原因是静态资源路径没对上，或者反向代理（如 Nginx、Ingress）截断了 /swagger/ 下的子路径请求。

• 检查浏览器开发者工具 Network 标签页，看 /swagger/swagger.json 是否返回 404 —— 如果是，说明 docs.Handler 没挂到正确路径
• Ingress 配置里如果用了 nginx.ingress.kubernetes.io/rewrite-target: /，会导致 /swagger/ 被重写成根路径，需改成 /swagger/$2 并调整 path 规则
• Docker 镜像里确认 docs/docs.go 已编译进二进制（执行 strings your-binary | grep swagger.json 可验证）
• 如果用的是自定义 ServerName 或 HTTPS 重定向中间件，确保 docs.Handler 在重定向逻辑之前注册

文档生成本身不依赖运行时环境，但服务暴露路径和反向代理配置才是上线后最常卡住的地方。