godoc 和 swag 解决不同问题：godoc 生成代码内联文档（包/函数说明），仅支持导出标识符的紧邻注释，goland 中按 ctrl+q 查看或用 go doc -http 启服务；swag 生成 openapi http api 文档，需规范注释、json tag 和显式执行 swag init，且不识别闭包或非导出函数。
godoc 和 swag 是 GoLand 项目里最常被混用的两个文档生成路径，但它们解决的问题完全不同：前者是代码内联文档（包级、函数级说明），后者是 HTTP API 文档（OpenAPI 规范）。选错工具，后续所有操作都白搭。
用 godoc 查看或托管本地代码文档
GoLand 自带对 godoc 的支持，但默认不启用 Web 服务。它适合快速查看自己或第三方包的结构说明，而不是对外发布。
-
godoc只读取紧邻声明的注释（比如func上方不能有空行），且必须是导出标识符（首字母大写）才可见 - 在 GoLand 中按
Ctrl+Q（Quick Documentation）就能弹出当前符号的godoc内容，无需额外配置 - 想启动本地文档服务器？终端执行
godoc -http=:6060，然后访问http://localhost:6060—— 但注意：Go 1.26+ 已移除内置godoc命令，需改用go doc -http=:6060 - 如果页面空白或报
no such file，大概率是没在项目根目录运行，或go.mod未正确初始化
用 swag 生成 Swagger UI API 文档
这是你在 GoLand 里真正需要“生成”的自动化文档——对应 HTTP 接口，能跑在浏览器里、支持试调、可导出 JSON。
GoLand 2026.1.1
下载
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
- 先确保已安装：
go install github.com/swaggo/swag/cmd/swag@latest，并确认$GOPATH/bin在PATH中 - 注释必须写在 handler 函数正上方，且至少含
// @Summary和// @Router，中间不能有空行 - 结构体字段要加
json:"field_name"tag，否则@Success 200 {object} MyResp会渲染为空对象 - 在 GoLand 终端里执行
swag init -g cmd/myapp/main.go -d ./，显式指定入口文件比单纯swag init更可靠 - 生成的
docs/目录需手动 import 到 main 包，并用ginSwagger.WrapHandler(swaggerFiles.Handler)挂载路由（路径必须是/swagger/*any）
GoLand 里直接触发 swag init 的坑
别依赖 GoLand 的“External Tools”或“Run Configuration”一键封装 swag init —— 它容易继承错误的工作目录或环境变量，导致找不到 main.go 或解析失败。
- 在 GoLand 底部 Terminal 里 cd 到含
main.go的目录再执行命令，是最稳的方式 - 如果报
failed to parse Go files，先运行go build ./确认代码能编译；再检查报错文件里是否有乱码、未闭合的字符串、或// swagger:注释格式错乱（比如冒号后没换行） - Swag 不识别闭包内的函数、匿名 handler、或非导出函数，哪怕你写了注释也没用
- 修改注释后必须重新运行
swag init，GoLand 不会自动监听变更
json: tag，接口就少一个字段；@Router 路径写错一个字符，Swagger UI 里就 404。这些细节不会报编译错误，但会让文档彻底失效。
