为何swag init仅生成通用API信息？多目录解析失败咨询

针对你遇到的仅解析cmd/app/main.go注释、internal目录文件注释未识别、paths字段为空且有常量解析警告的问题，可按以下步骤排查解决：

1. 确认internal包已被入口文件正确导入 #

Swaggo是从-g指定的入口文件出发，递归解析其实际依赖的包。如果internal/transport/http/v1下的代码没有被main.go直接/间接导入（比如路由注册时没用到auth.go、trip.go里的Handler），即使加了--parseInternal也不会触发解析：

• 检查main.go中是否导入了目标包：import "your-project/internal/transport/http/v1"
• 确保代码中实际使用了该包的Handler（比如r.POST("/auth", v1.AuthHandler)这类路由注册代码）

2. 校验Swagger注释格式规范 #

注释格式错误是导致paths为空的常见原因：

• 每个API Handler的注释必须以// @Summary开头，且必须包含// @Router字段指定路径和HTTP方法（如// @Router /api/v1/auth [post]），缺少@Router会导致Swaggo不生成对应paths条目
• 注释必须与对应的Handler函数直接相邻，不能有空行隔开
• 常量解析警告需检查注释中的常量引用：比如注释里用default({{.ConstVal}})时，确保常量ConstVal在当前包或已被正确导入，避免因解析失败影响整体扫描

3. 调整swag init命令参数 #

尝试显式指定要解析的目录，避免依赖自动递归的缺陷：

swag init -g cmd/app/main.go --parseInternal --parseDependency -d ./cmd/app,./internal/transport/http/v1

• -d参数明确列出需要解析的目录，多个目录用逗号分隔
• 确保在项目根目录执行该命令，而非cmd/app子目录

4. 升级Swaggo版本 #

swag 1.8.12存在部分老版本兼容性问题（比如对Go 1.20的适配），升级到最新稳定版可解决已知的递归解析bug：

go install github.com/swaggo/swag/cmd/swag@latest

5. 检查Go模块配置 #

确保项目已启用Go模块（存在go.mod文件），且internal包的导入路径正确，避免因路径错误导致Swaggo无法定位依赖包。

内容的提问来源于stack exchange，提问作者dogbullet