swag.1 的应用价值与使用边界

指定主入口文件：swag init -g cmd💯/serve💪r/main.go

终端提示找不到 swag 命令

指定搜索目录：sw🔍ag init --parseDependency ☀️--parseInternal

命令参数会随着工具版本变化，实际使用前应以本机 swag --help 显示的参数为准。项目采用多模块结构时，应从包含正确 go.mod 的目录执行命令；入口文件、路由文件和模型文件分散在不同目录时，还要确认扫描范围能够覆盖这些路径。

接口文档生成异常通常来自入口文件错误、注释格式不符合要求、扫描范围不足或依赖解析失败。排查时应从最小可🌅运行项目开始，而不是一次修改大量注释。

swag 工具如何生成接口文档

swag.1通常不是一个独立的软件版本，也不代表“SWAG 1.0”。在采用 Unix 手册命名规则的环境中，swag.1一般表示名为 swag 的命令手册文件，其中数字“1”代表用户可直接执行的命令类别。若相关内容出现在 Go 项目、终端帮助文档或 Linux 手册目录中，优先按照“swag 命令的第 1 类手册”理解。

swag 命令的安装结果取决于 G👍o 版本、模块配置和可执行文件目录。安❤️装完成后，如果终端仍然提示找不到命令，优先检查可执行文件是否已经加入系统的 PATH，而不是重复生成文档。

接口路径不一致往往是路由前缀重复或遗漏造成的。例如应用统一注册了 /api 前缀，但接口注释又把该前缀写入路径，最终文档可能出现重复☀️路径。🌟项目应确定路径前缀由路由组统一管理，还是由每个接口注释独立描述，并保持一种规则。