Go语言集成Swagger是工程落地动作，需按规则写注释、组织包、挂载路由；swag init扫描路径需显式指定，注释字段须字面匹配，静态资源须正确挂载，且满足UTF-8编码、结构体导出与json tag等硬性条件。
Go 语言集成 Swagger 实现接口自动化文档，不是“学语言”的路径，而是工程落地动作——它不帮你理解 Go 语法或并发模型，只解决“如何让接口定义和文档对齐”这一具体问题。你不需要先学完 Go 再做 Swagger，但必须按它的规则写注释、组织包、挂载路由。
swag init 扫不到接口？检查扫描路径和入口文件
执行 swag init 后 docs/swagger.json 里 paths 为空，90% 是因为没扫到 handler 文件。swag 默认只看当前目录及其子目录下属于同一 module 的 .go 文件，不自动跨路径。
- 如果路由分散在
internal/handler和pkg/api，必须显式指定：swag init -d internal/handler -d pkg/api - 入口文件（如
cmd/app/main.go）含r.GET()调用，就得用-g指定：swag init -g cmd/app/main.go - handler 文件不能是
package main（除非它真注册了路由），推荐统一用package router或package api - 所有被扫描的
.go文件必须有合法package xxx声明，且不能有语法错误，否则整文件被跳过
@Param 或 @Success 字段不显示？类型和结构体声明必须硬匹配
swag 不读 Go 类型系统，也不反射结构体，它只按注释字符串字面解析。写错一个词，就静默跳过，不会报错提示。
-
@Param id path string true "用户ID"✅ —— 路径参数类型只能是string、int、bool、float64；别写int64或uuid.UUID -
@Param user body model.User true "用户信息"✅ ——body参数必须指向已定义 struct，且该 struct 上方需有// @Model注释 -
@Success 200 {object} model.UserResponse✅ ——model.UserResponse必须可导入（即所在包已import），字段首字母大写 +json:"xxx"tag，否则 schema 里字段为空 - 数组参数不能写
type: []string，得写成：@Param ids query array true "ID列表" collectionFormat:multi items.type:string
/swagger/index.html 404 或空白？静态资源挂载方式不对
生成 docs/ 目录 ≠ 自动注册路由。Swagger UI 是 SPA，依赖 History API，不能当普通静态文件挂。
立即学习“go语言免费学习笔记（深入）”；
- 必须确保
swag init成功后存在docs/docs.go和docs/swagger.json；不存在说明上一步就失败了 - Gin 用户要这样挂：
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))——*any不能省，否则/swagger/swagger-ui.css等子资源全 404 - 必须 blank import docs 包：
import _ "your-module-name/docs"，否则swaggerFiles.Handler拿不到初始化数据 - 千万别用
r.Static("/docs", "./docs")，这会导致 UI 加载卡在doc.json 404
中文乱码、响应显示 “object”、字段全空？三个硬性条件缺一不可
文档加载后中文变 \u4f60\u597d，或点开响应 schema 全是空对象，不是配置问题，而是代码没满足 swag 的硬性要求。
- 源码文件必须 UTF-8 编码且无 BOM
- 所有 handler 函数上方必须紧贴函数声明（中间不能有空行），且第一行是
// @Summary；缺这一行，整个函数被忽略 - 结构体字段必须导出（首字母大写）+ 显式
json:"xxx"tag；没有 tag 就不会出现在 schema 中 - 生产环境务必禁用 Swagger：通过构建 tag 或环境变量控制是否 import
docs包，避免暴露接口细节
最常被忽略的点是：swag 不报错，只静默跳过。你以为注释写对了，其实少了一个空格、多了一个冒号、或者 struct 没加 @Model，它就当没看见。验证是否生效，唯一可靠方式是打开 docs/swagger.json，直接查 paths 和 components.schemas 里有没有你预期的内容。
