swag init 失败的根本原因是模块路径、注释格式、扫描目录和路由挂载不合规：必须在 go.mod 目录执行，模块名含点号，-g 指定入口，-d 显式指定 handler 目录，@Summary 为首行，Gin 需用 ginSwagger.WrapHandler 正确挂载。
swag init 总是失败？先确认项目结构和模块路径
根本不是 GoLand 配置问题，而是 swag init 对目录和模块名有硬性要求。GoLand 只是编辑器，它不干预构建逻辑——但容易让人误以为“点运行就能生成文档”。
- 必须在
go.mod所在目录执行swag init，不能在 GoLand 的 project root（比如桌面或空白文件夹）直接右键运行 - 模块名必须含点号，例如
example.com/myapi；写成myapi或my_api会导致cannot determine module path - 如果项目用
cmd/main.go入口，swag init -g cmd/main.go是必需的，否则找不到路由注册逻辑
注释写对了，但接口没出现在 swagger.json 中？检查 handler 文件归属
swag 不按函数调用链扫描，只静态解析指定目录下属于同一 module 的 .go 文件。GoLand 里看着代码都在一个 project 里，但 Go 的 import 路径错一点，整个文件就被跳过。
- 确保所有 handler 函数所在文件的
package声明合法（比如package handler），且没有语法错误 - 如果 handler 分散在
internal/handler和api/v1，必须显式加-d internal/handler -d api/v1 -
// @Summary必须是注释块第一行，前面不能有空行、/* */块注释、或非注释字符 - 函数签名里有没有参数、返回值，不影响扫描——但注释里
@Param和@Success缺一不可
Gin 项目里访问 /swagger/index.html 404？别用 Static 挂载 docs/
GoLand 运行配置里启动服务没问题，但 404 是因为 Gin 没正确注册 Swagger UI 的路由处理器，不是端口或路径写错。
GoLand 2026.1.1
下载
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
- 必须用
ginSwagger.WrapHandler(swaggerFiles.Handler)，不能用r.Static("/swagger", "./docs") - 挂载顺序必须在所有业务路由之后、
r.Run()之前；放在gin.Default()后立刻注册会失效 - 路由写法必须是
r.GET("/swagger/*any", ...)，*any是 Gin 的通配符，漏掉或写成/*就加载不了swagger-ui.css等资源 -
docs/docs.go必须存在且已go generate过，否则swaggerFiles.Handler是空的
中文注释变 \u4f60\u597d？检查文件编码和 struct 字段导出规则
GoLand 默认用 UTF-8，但文档乱码往往来自两个更隐蔽的地方：结构体字段没导出，或 json tag 写错。
- 所有要出现在文档里的 struct 字段，首字母必须大写（导出），且带
json:tag，例如Name string `json:"name"` - 如果字段写了
json:"-"或json:"name,omitempty"但没给默认值，字段可能被忽略，显示为空 object - 数组类型如
[]User，@Success必须写{array}User，不能写{object}或array[User] - Swag 不识别
uuid.UUID这类非基础类型，得用@Param id path string+ 在 handler 里做转换，或提前用// @Model声明
GoLand 本身不参与文档生成逻辑，真正卡住的永远是模块路径、注释位置、扫描范围和路由挂载这四件事。每次改完注释，记得删掉旧的 docs/ 目录再跑 swag init，不然缓存会掩盖新问题。
