Swag init仅生成通用API信息，无法解析多目录Swagger注释

问题现象 #

• 执行以下两个swag init命令结果完全一致：

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

• 仅能解析-g标记指定的cmd/app/main.go文件中的Swagger注释，internal/transport/http/v1下的auth.go、trip.go等文件的注释未被识别
• 生成的swagger.yaml中paths字段为空，仅保留通用API基础信息
• 环境：swag v1.8.12，Go v1.20.2，OSX

解决步骤 #

• 检查注释规范与依赖导入

  • 确保internal目录下的API函数注释符合Swaggo要求，必须包含// @Summary、// @Router等核心标签，且注释块与对应函数之间不能有空行
  • 确认main.go中已正确导入internal/transport/http/v1包，Swaggo需要通过依赖链识别目标文件，即使显式指定目录，未导入的包也会被忽略

• 调整命令参数

  • 尝试移除--parseDependency参数，仅保留--parseInternal，OSX下多目录用逗号分隔（无空格）：

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

  • 若问题仍存在，可尝试直接指定需要解析的文件（用于排查目录解析问题）：

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

• 升级Swaggo版本

  • v1.8.12存在部分目录递归解析的已知bug，升级到最新稳定版可解决多数兼容性问题：

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

  • 升级后重新执行初始化命令验证结果

• 检查Go模块配置

  • 确认项目已通过go mod init初始化模块（存在go.mod文件），Swaggo依赖模块路径识别文件归属
  • 确保internal目录下的文件属于当前模块，无跨模块引用导致的解析异常

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