GoLand 本身不内置 API 文档生成功能，但可通过集成 swag 工具链实现一键生成 swagger.json 并刷新 Swagger UI；关键在于项目结构、注释规范及命令参数需严格匹配 swag 的静态解析要求。
GoLand 本身不内置 API 文档生成能力，但可以无缝集成 swag 工具链，实现点击按钮就生成 docs/swagger.json 并自动刷新 Swagger UI。关键不在 IDE 配置，而在于项目结构、注释规范和命令调用方式是否对齐 swag 的静态解析逻辑。
swag init 扫不到接口？先确认 GoLand 当前工作目录和扫描路径
GoLand 运行 Terminal 或 External Tools 时，默认工作目录是「当前打开的项目根目录」，但 swag init 要求：必须在包含 go.mod 的目录执行，且显式指定入口文件和 handler 所在路径。否则 docs/swagger.json 中 "paths":{}，文档页面空荡荡。
- 检查 GoLand 底部 Terminal 的 pwd 是否为项目根目录（含
go.mod） - 若
main()在cmd/app/main.go，必须加-g cmd/app/main.go - 若 handler 分散在
internal/handler和pkg/api，需用-d internal/handler -d pkg/api - 别把路由注册写在
package main文件里——swag会跳过它；应单独建package router并确保该文件有合法package router声明
@Param 和 @Success 注释写错一个字符，字段就消失
swag 不解析 Go 类型系统，只认硬编码类型名和已声明结构体。注释里写错大小写、漏掉必填标记、或结构体没导出，都会导致参数/响应体在 UI 中显示为 “object” 或完全空白。
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
- 路径/查询/请求头参数只能用
string、int、bool、float64；写int64或uuid.UUID直接报错或静默忽略 - 请求体必须用
body位置：// @Param user body model.UserCreate true "用户信息"；写成query或path不会报错，但参数不会出现在 UI 表单中 -
@Success 200 {object} model.UserResponse中的model.UserResponse必须已 import，且结构体字段全部首字母大写 + 带json:tag，例如Username string `json:"username"` - 数组参数不能简写：
@Param ids query array true "ID列表" collectionFormat:multi items.type:string，不是type: []string
在 GoLand 里一键运行 swag init（避免 Terminal 手动输命令）
GoLand 支持配置 External Tool，绑定快捷键后，点一下就能生成文档，比每次敲命令快得多。重点是命令参数要完整，且输出目录与代码中引用的 docs 包路径一致。
- 打开 Settings → Tools → External Tools，点击
+ - Program：填
swag（确保已go install github.com/swaggo/swag/cmd/swag@latest） - Arguments：填
init -g cmd/app/main.go -d internal/handler -d pkg/api -o ./docs（按你项目实际路径调整） - Working directory：填
$ProjectFileDir$（即项目根目录） - 勾选 “Run console in background”，方便快速查看错误输出
- 生成后，GoLand 会自动识别新出现的
docs目录；若后续在代码中 import"your-project/docs"，IDE 不会报 red-squiggle
中文乱码、响应 schema 全空？不是 GoLand 设置问题，是源码硬伤
Swagger UI 显示 \u4f60\u597d 或点开 response schema 一片空白，90% 是 Go 源文件或注释本身不符合 swag 的三个底层要求，跟 GoLand 字体/编码设置无关。
- 所有
.go文件必须保存为 UTF-8 无 BOM 格式（用file -i your_handler.go检查；若显示ISO-8859，用 VS Code 或 GoLand 的 “File → File Encoding → UTF-8” 重存） - 注释里不能粘贴自微信、Word 或网页的中文引号、全角空格、不可见换行符（建议手打或用纯文本编辑器清理后再粘贴）
- 结构体字段即使首字母大写，也必须带
json:tag；time.Time字段建议显式加time_format:，否则可能被转成数字时间戳
真正卡住人的地方，从来不是怎么配 GoLand，而是 swag 对注释格式、包声明、结构体定义的硬性约束——它不执行代码，只靠字符串匹配；少一个 true，缺一个 json:"id"，生成结果就断层。文档能跑起来，说明项目结构和注释已经踩过一遍坑了。
