GoLand配置GoSwagger工具根据代码注释生成接口文档-Golang-PHP中文网

goland仅支持swaggo/swag而非go-swagger，需用go install安装swag cli并配置external tools一键生成文档，注释须紧贴func且含@summary/@router，静态路由需手动注册才能访问swagger ui。

goland配置goswagger工具根据代码注释生成接口文档

GoLand 本身不内置 GoSwagger（即 go-swagger），它只支持基于注释的 swag（swaggo/swag）——这是当前 Go 生态中唯一能稳定在 IDE 内联动、无需先写 spec 就能从代码生成文档的方案。别被名字误导，“GoSwagger”常被误指代 swag，但二者完全不兼容：go-swagger 是契约先行、从 YAML 生成代码；swag 是代码先行、从注释生成 OpenAPI。

GoLand 里怎么装对 swag CLI？不是 go get

GoLand 的 Terminal 或 External Tools 调用的是系统 PATH 下的 swag，必须用 Go 1.21+ 推荐方式安装：

go install github.com/swaggo/swag/cmd/swag@latest —— 注意末尾的 @latest，缺了会装旧版或失败
装完运行 swag version 确认输出类似 swag version v1.17.0，不是 command not found
如果 GoLand 找不到 swag，进 Settings → Go → GOPATH 检查是否勾选了 “Use GOPATH that is defined in system environment”，否则它可能用内置 sandbox 路径，不读你 shell 的 PATH

在 GoLand 里一键运行 swag init 的正确姿势

别在 Terminal 手敲命令，用 External Tools 绑定，避免路径错、参数漏：

GoLand 2026.1.1

GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。

下载

进 Settings → Tools → External Tools，点 + 添加新工具
Name: 填 swag init；Program: 填 swag（确保已在 PATH）
Arguments: 填 init -g $ProjectFileDir$/cmd/myapp/main.go -d $ProjectFileDir$/internal/handler -o $ProjectFileDir$/docs —— 必须显式指定 -g 入口和 -d handler 目录，否则扫不到接口
Working directory: 填 $ProjectFileDir$ ，确保在 module 根目录执行
配好后右键项目根目录 → External Tools → swag init，就能一键生成 docs/docs.go 和 docs/swagger.json

注释写在哪、怎么写，GoLand 才能高亮且 swag 才能扫到

GoLand 对 // @ 注释有语法高亮和拼写检查，但前提是位置和格式严丝合缝：

注释块必须紧贴 func 声明正上方，中间不能有空行、不能有其它 // 或 /* */
每个 handler 至少含 // @Summary 和 // @Router，缺一个 swag init 就跳过该函数
// @Param id path int true "ID" 中的 path 必须小写，不能写成 Path 或 PATH；类型只能是 string/int/bool/float64，别写 int64
结构体响应如 // @Success 200 {object} models.User，要求 models.User 是导出类型（首字母大写）、字段带 json: tag，否则 schema 里字段为空

生成 docs 后，GoLand 调试时看不到 Swagger UI？挂路由这步最容易漏

GoLand 运行服务只是启动 HTTP server，docs/ 目录不会自动暴露 —— 必须手动注册静态路由，且路径通配符不能错：

确认 docs/docs.go 已生成（没这个文件说明 swag init 根本没跑成功）
Gin 用户：用 router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))，注意 *any 不能省，否则 /swagger/swagger-ui.css 404
标准 net/http 用户：得用 http.Handle("/swagger/", http.StripPrefix("/swagger/", http.FileServer(http.Dir("./docs"))))，路径前缀和 Dir 要对齐
改完代码后，在 GoLand 点 ▶️ 运行，再访问 http://localhost:8080/swagger/index.html —— 如果白屏或 404，先 curl 看 /swagger/swagger.json 能否返回 JSON