swag init 报“no Go files found”因默认仅扫描含// @title且属main或已导入包的.go文件；Swagger UI加载swagger.json失败多因路径映射错误或docs/docs.go未被import；@Param需严格格式且大写；微服务中host硬编码导致请求发往localhost，应动态设置或显式声明@host。
为什么直接用 swag init 会报 “no Go files found”？
因为 swag init 默认只扫描当前目录下带 // @title 注释的 .go 文件，且要求这些文件属于 main 或已声明的包（不能是空包或未导入的包）。常见错误是把 Swagger 注释写在 handler.go 里，但该文件所在目录没有 package main 或没被任何 main 包 import —— swag 就当它不存在。
- 确保至少一个
.go文件里有package main，且该文件包含// @title等基础注释 - 如果路由分散在多个子包（如
api/v1），需用-d指定根目录：swag init -d ./ - 避免在
go:generate注释里漏掉-g参数：正确写法是//go:generate swag init -d ./
如何让 Swagger UI 正确加载 swagger.json 而不是 404？
Go 微服务通常用 http.ServeFile 或第三方库（如 swag.Handler）暴露 UI，但路径映射错位会导致 JSON 加载失败。关键不是“能不能打开 UI”，而是浏览器控制台是否报 Failed to load spec —— 这说明 /swagger/doc.json 返回了 404 或 HTML。
- 用
swag.Handler时，必须注册在/swagger/*路径下：r.Get("/swagger/*any", swagger.Handler)（用 Gin） - 手动托管时，确保
swagger.json可通过GET /swagger/swagger.json直接访问（不是/docs/swagger.json） - 检查
swag init输出的docs/docs.go是否被import—— 否则swag.Handler读不到内嵌数据
// @Param 怎么写才不会被忽略？
Swagger 注释解析对格式极其敏感：@Param 必须紧贴函数上方，且参数名、类型、位置（path/query/body）三者缺一不可，否则字段不显示或类型变成 string。
- 路径参数必须和路由定义一致：
// @Param id path int true "user ID"对应GET /users/{id} - 请求体必须指定结构体名：
// @Param user body model.User true "user info"，且model.User需为导出类型 - 查询参数若为切片，要写
array类型：// @Param tags query []string false "tags" - 别用
@param（小写）—— swag 只识别大写的@Param
微服务多实例部署时，Swagger 文档为何总显示 localhost？
因为 swag init 生成的 docs/docs.go 里硬编码了 host: "localhost:8080"，而微服务实际跑在 Kubernetes 或 Docker 中，外部访问走的是网关域名。Swagger UI 发起请求时仍往 localhost 发，必然失败。
立即学习“go语言免费学习笔记（深入）”；
- 删掉
// @host localhost:8080注释，swag 会自动用请求头中的Host字段 - 或显式设为网关地址：
// @host api.example.com（注意不要带https://） - 更稳妥的做法是在启动时动态注入：
swag.SetWebPath("/swagger")不够，得改docs/docs.go中的SwaggerInfo.Host变量
真正麻烦的不是生成文档，而是让每个服务的文档能真实反映它当前可访问的端点。一旦用了服务发现或 API 网关，就得放弃静态 host，转而依赖请求上下文。
