swaggo/swag是Go生态唯一稳定落地的API文档自动生成方案，通过静态解析源码注释生成OpenAPI 3.0文档；需严格配置扫描路径、入口文件、package声明、@Model注释及参数类型格式，并手动挂载Swagger UI路由。
Go语言生态中，接口文档自动化生成的主流且稳定落地的方案是 swaggo/swag。它不依赖运行时反射，而是静态解析源码注释，直接生成符合 OpenAPI 3.0 规范的 swagger.json，再由 Swagger UI 渲染为可交互的网页文档。整个过程零运行时开销，改注释即更新文档，真正实现“代码即文档”。
确保 swag 能正确扫描到接口
常见问题如 paths 为空、UI 显示首页但无接口列表，几乎都源于扫描范围配置不当：
- 默认只扫描当前目录及子目录下属于同一 Go module 的
.go文件；若 handler 分散在internal/handler、pkg/api等路径，必须显式指定：swag init -d internal/handler -d pkg/api - 入口文件（如
cmd/app/main.go）要用-g指定：swag init -g cmd/app/main.go，否则可能漏掉跨包注册的路由逻辑 - 被扫描的文件不能是
package main（除非它真包含r.GET()这类注册），推荐把路由逻辑单独放在package router或package api - 所有 handler 文件必须有合法
package xxx声明，且不能含语法错误，否则整文件被跳过
注释写法必须严格合规
swag 对注释格式极其敏感，一个标点错误就可能导致字段丢失或静默跳过：
- 每个 handler 函数上方需紧贴声明（中间不能有空行），包含至少
// @Summary、// @Success、// @Router三类基础注释 -
@Param中路径/查询/请求头参数只能用string、int、bool、float64，不可写int64或uuid.UUID；请求体（in: body）必须指向已定义 struct，且该 struct 上方需有// @Model注释 -
@Success 200 {object} model.User中的model.User必须可导入（即所在包已import），结构体字段需导出（首字母大写）并带json:"xxx"tag，否则不会出现在 schema 中 - 数组参数不能简写为
type: []string，而应写为：@Param ids query array true "ID列表" collectionFormat:multi items.type:string
集成 Swagger UI 到 HTTP 服务
生成 docs/ 目录后，必须手动挂载才能访问 /swagger/index.html：
立即学习“go语言免费学习笔记（深入）”；
- Gin 用户：导入
github.com/swaggo/gin-swagger和github.com/swaggo/files，加一行r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) - Echo 用户：用
github.com/swaggo/echo-swagger，调用e.GET("/swagger/*", echoSwagger.WrapHandler) - net/http 用户：用
http.FileServer挂载，注意路径映射：http.Handle("/swagger/", http.StripPrefix("/swagger/", http.FileServer(http.Dir("./docs")))) - 生产环境建议关闭此路由，避免暴露内部接口细节
应对复杂结构与 CI/CD 自动化
真实项目常遇到泛型封装、嵌套 error、中间件注入等场景：
- 对泛型响应（如
Result[T]），swag 无法自动推导T，需手动指定：// @Success 200 {object} model.Result{data=model.User}，且Result类型需标注// swagger:model - 中间件参数（如 JWT token、权限头）虽不直接出现在 handler 签名中，但可通过注释说明：
// @Header 200 {string} X-Auth-Token "JWT Token" - 建议将
swag init纳入 CI/CD 流程：每次提交后自动执行；检查生成的docs/swagger.json是否已提交，未提交则阻断流水线；部署阶段将文档打包进静态资源供内部访问
