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在重定向逻辑之前注册
文档生成本身不依赖运行时环境，但服务暴露路径和反向代理配置才是上线后最常卡住的地方。
