GoLand Swagger插件仅是swag CLI的图形化封装，需先确保swag可执行文件已正确安装并加入PATH，再配置-g、-d、-b等关键参数，且注释格式必须严格规范。
GoLand 本身不支持 Swagger 文档自动生成，插件只是快捷入口，真正干活的是 swag CLI —— 配了插件但没装 swag、没写对注释、没指定扫描路径，照样生成失败。
GoLand 插件只是个 shell 封装，swag 才是核心
GoLand 的 “Swagger” 插件（如 Swagger Generator 或社区版 Swaggo Support）本质只是调用你本地的 swag 可执行文件，并传参运行。它不解析 Go 代码、不校验注释格式、也不处理模块路径问题。
- 插件点击“Generate Swagger Docs”后，实际执行的是类似
swag init -g cmd/myapp/main.go -d internal/handler -o docs/的命令 - 如果终端里手动运行
swag init都报错，插件必然失败，且错误信息更模糊 - 插件无法绕过
swag的硬性限制：比如@Param类型只认string/int，不认uuid.UUID；结构体字段必须导出+带json:tag - 插件默认扫描路径常是当前目录，微服务项目中
handler在internal/handler下时，必须进插件设置里手动填-d internal/handler
插件配置前，先确保 swag CLI 能在终端跑通
别跳步。插件依赖 swag 可执行文件在 $PATH 中可用。GoLand 默认用系统 Shell 环境，但有时会读不到你 ~/.bashrc 或 ~/.zshrc 里的 export PATH。
GoLand 2026.1.1
下载
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
- 在 GoLand 终端（Terminal 标签页）里直接输入
swag version，必须返回版本号（如v1.17.0），否则插件点不动 - 安装方式必须是：
go install github.com/swaggo/swag/cmd/swag@latest（go get在 Go 1.21+ 已弃用） - 确认
GOBIN在PATH中：运行go env GOBIN，把输出路径加到系统PATH，或在 GoLand → Settings → Tools → Terminal → Shell path 里指定完整 shell 启动脚本（如/bin/zsh --login） - 项目根目录下必须有合法的
go.mod，且swag init命令要在该目录执行——插件也一样，它不帮你cd
插件里最容易漏掉的三个参数
多数插件 UI 只暴露“入口文件”和“输出目录”，但实际 swag init 至少还需要三个关键参数才能扫到接口，缺一不可：
-
-g cmd/myapp/main.go：显式指定入口文件。插件若没填，它就默认用当前目录下的main.go，而微服务常把main放在cmd/xxx/下，结果路由注册逻辑压根没被解析 -
-d internal/handler和-d api/v1：handler 文件分散时必须重复加-d。插件通常只给一个“scan directory”输入框，填多个路径要用空格或逗号分隔（看插件文档），否则只扫第一个 -
-b /api/v1：如果 API 有统一前缀，必须加这个，否则生成的swagger.json里paths是/users，但真实路由是/api/v1/users，UI 里点“Try it out”直接 404
生成后 404？插件不管静态资源挂载
插件只负责运行 swag init 生成 docs/ 目录，它不会、也不能帮你改 Go 代码去注册 /swagger/*any 路由。
- 检查
docs/下是否存在docs.go和swagger.json：没有说明上一步就失败了，别急着配路由 - 用 Gin 时，必须手写：
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))—— 注意是*any，不是*或/** - 用
net/http时，得写：http.Handle("/swagger/", http.StripPrefix("/swagger/", http.FileServer(http.Dir("./docs")))) - 路径大小写敏感：
/Swagger或/docs都会导致 404，浏览器访问必须是小写/swagger/index.html
最常被忽略的一点：所有 // @ 注释必须紧贴 handler 函数上方，中间不能有空行、不能有其它 // 行、不能混入中文引号或全角符号。swag 解析器遇到语法错误直接跳过整个函数，还一声不吭。
