根本原因是swag仅扫描源码注释且对格式极度敏感：需在main包目录执行或用-g指定入口文件，-d显式声明分散的handler路径；注释须紧贴函数无空行、类型用基础名、结构体带包名和json tag。
swag init 报错 ParseComment 或找不到 handler 怎么办
根本原因通常是路径或注释结构不合规。swag 不分析运行时路由，只扫描 Go 源码文件中的注释块，所以必须确保：swag init 在包含 main() 的包目录下执行；若 main.go 不在项目根目录（比如在 cmd/myapp/main.go），必须显式指定：swag init -g cmd/myapp/main.go。
- 结构体字段没加
json:tag → swag 无法推导请求/响应字段，参数或响应体显示为空 - handler 函数上方注释和函数声明之间有空行 → 注释不被识别，整个接口消失
- 用了未导入的类型名（如写
{object} User而非{object} model.User）→ParseComment error报错 - 微服务多 module 结构（如
api/、model/）→ 必须用-d指定扫描路径：swag init -d ./api,./model
Gin/Echo 中挂载 Swagger UI 的常见失灵点
生成 docs/ 目录后，文档静态资源不会自动暴露——这是最常被忽略的一步。Gin 和 Echo 处理方式不同，但核心都是把 docs 当作静态文件服务，并提供 HTML 入口。
- Gin：需先
import _ "your-module-path/docs"（注意是空白导入），再用ginSwagger.WrapHandler(docs.SwaggerInfo)；漏掉 import 会导致docs.SwaggerInfo未定义 - Echo：不能只靠
echo.Static("/swagger", "./docs")，因为 Swagger UI 主页是/swagger/index.html，而Static不处理子路径重定向；建议改用echo.File("/swagger/*", "./docs/index.html")或手动注册GET /swagger/index.html - Docker 镜像里访问 404？确认构建阶段已
COPY docs/ docs/，否则容器内根本不存在该目录
@Param 和 @Success 注释怎么写才不出错
swag 对注释语法极其敏感，一个标点错位就会导致字段丢失。它不校验 Go 类型合法性，只按字符串规则解析，所以格式必须严格匹配。
-
@Param id path int true "user ID"→ 正确：路径参数，类型写int，不是int64或"int" -
@Param q query string false "search keyword"→ 查询参数类型统一用string，即使后端接收的是int，文档侧仍写string -
@Success 200 {object} model.User→ 必须带包名；{array} model.User才表示数组，不能只写{array} -
@Failure 404 {object} model.ErrorResp→ 错误响应也需完整类型路径，且结构体字段同样要导出 +json:tag
CI/CD 中自动生成文档的坑与对策
本地能跑不等于上线可用。CI 流程中容易因环境差异导致文档生成失败或内容缺失。
立即学习“go语言免费学习笔记（深入）”；
- Go 版本升级后
go install命令行为变化 → 始终用go install github.com/swaggo/swag/cmd/swag@latest，避免残留旧版缓存 - CI 并行构建多个微服务时，
swag init可能扫描到其他模块的 handler → 用-d精确限定目录，禁用--parseDependency - 生产环境意外暴露
/swagger→ 启动时加开关控制，例如只在ENV != "prod"时注册 Swagger 路由 - 注释更新但忘记
swag init→ 在 CI 的 build step 加校验：生成后检查docs/swagger.json是否含预期接口数，或用swag fmt强制格式化并检测语法
json: tag 或一条空白行，文档就可能静默失效——这种问题往往要等到前端联调时才暴露。 
