goland 无法真正实现“保存即自动触发 swag init”，仅能通过 file watchers 模拟，且需严格限定监听目录、显式指定 -g/-d 参数、确保注释规范、项目路径正确，并依赖手动重跑以响应结构体字段变更。
GoLand 保存时自动触发 swag init 的真实限制
GoLand 本身不支持“保存 Go 文件就自动运行 swag init”——它没有内置的、能识别 Swagger 注释变更并精准触发文档重建的机制。所谓“自动更新”，只能靠外部工具链 + IDE 功能组合实现，且必须满足几个硬性前提：注释格式正确、扫描路径明确、swag CLI 可执行、项目结构被正确识别。
用 File Watchers 模拟“保存即生成”的操作路径
GoLand 的 File Watchers 插件可以监听 .go 文件保存事件，并执行命令。但它不会智能判断“这个文件里有没有 // @Summary”，只会无差别触发。所以你需要手动限定范围和条件：
- 只监听 handler 目录（如
internal/handler、api/）下的.go文件，避免每次改main.go或测试文件都跑一遍 - 命令必须显式指定入口和输出路径，例如：
swag init -g cmd/app/main.go -d internal/handler -o docs/ - 勾选
Auto-save edited files to trigger the watcher，否则仅靠 Ctrl+S 不生效 - 在
Advanced options中设置Working directory为项目根目录（即含go.mod的那层），否则swag找不到模块路径 - 别勾选
Trigger the watcher on external changes，防止swag init自身写入docs/时再次触发循环调用
swag init 失败时 GoLand 不报错，你得看 Terminal 输出
File Watchers 执行失败默认静默，不会弹窗或高亮错误。常见失败原因直接反映在 GoLand 底部 Terminal 或 Build 标签页里：
GoLand 2026.1.1
下载
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
-
failed to parse Go files：某个 handler 文件有语法错误（比如少括号），或用了golang.org/x/exp这类 swag 尚未支持的包 -
cannot find type definition for "uuid.UUID"：@Param 或 @Success 引用了未用// @Model声明的类型，或包名写错（如写了User而不是models.User） - 生成后
docs/docs.go编译报错：模块路径（go.mod第一行）和实际 import 路径不一致，比如模块名是example.com/api，但代码里 import 的是example.com/API -
swagger.json里paths为空：-d指定的目录下没有合法package xxx的 .go 文件，或所有 handler 函数上方缺// @Summary
比自动触发更可靠的做法：绑定到 Go Build 流程
与其依赖文件保存事件，不如把 swag init 当作构建前置步骤。GoLand 支持在 Run Configuration 的 Before launch 里添加 Run External Tool：
- 工具命令填
swag，参数填init -g cmd/app/main.go -d internal/handler -o docs/ - 工作目录设为
$ProjectFileDir$ - 勾选
Run on frame activation，这样每次切回 IDE 窗口时自动检查一次 - 配合
go build ./...一起运行，确保文档和二进制版本始终对齐
真正容易被忽略的是：swag init 不会检测结构体字段变更。你改了 User.Name 的 json: tag，但没动 handler 上的注释，文档里的 schema 就不会更新——必须手动再跑一次。
