swag init 生成的文档里没有接口，根本原因是未扫描到 handler 函数：默认只扫描同 module 下当前目录及子目录的 .go 文件，若 handler 分散在 internal/handler 等路径，需显式指定 -d 参数；且 handler 必须被 -g 指定的入口文件 import 到、不能是 package main 或 _test.go 文件，函数需导出、注释紧邻声明、@Router 路径与实际路由完全一致。
swag init 生成的文档里没有接口？不是注释写得不对，而是它根本没扫描到你的 handler 函数。
swag init 扫不到 handler 函数的真正原因
swag 不是运行时反射工具，它只静态解析 Go 源文件 AST。默认只扫当前目录及子目录下、与入口文件同 module 且能被 go list 正常加载的 .go 文件。如果你的 handler 分散在 internal/handler 或 pkg/api，又没显式指定路径，它就直接跳过。
- 执行
swag init -g cmd/app/main.go，强制从入口文件开始递归解析 import 链 - 所有含
@Summary和@Router的 handler 文件，必须被main.go直接或间接 import，不能是“孤岛包” - 别把 handler 放在
package main里（除非它真注册了路由），swag 会跳过非 router/api 类型的 main 包 - 确保 handler 文件不是
_test.go—— swag 默认忽略测试文件
@Param 和 @Success 写错类型导致 schema 为空
swag 的类型解析器和 Go 编译器不一致：它不认识 uuid.UUID、int64、[]string 这类写法，只认基础类型名和已用 // @Model 显式声明过的 struct。
- 路径/查询参数只能写
string、int、bool、float64；别写int64或uuid.UUID - 请求体（
in: body）必须指向一个导出 struct，且该 struct 上方要有// @Model注释 -
@Success 200 {object} models.User中的models.User必须带完整包名；返回指针要写成*models.User - 数组查询参数不能简写为
type: []string，得写成collectionFormat:multi items.type:string
中文乱码、响应字段全空、浏览器打开显示 “object”
这不是前端或配置问题，是结构体定义没满足 swag 的硬性解析条件：字段没加 json: tag、未导出、或跨 module 引用没声明 // @modelsPackage。
Alibabacloud Sdk Client Initialization For Golang
下载
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
立即学习“go语言免费学习笔记（深入）”；
- struct 字段必须首字母大写（导出），且每个字段带
json:"field_name"tag，否则不会出现在 schema 中 - 嵌套 struct 必须在同一 module 下，或在引用处加
// @modelsPackage github.com/your/project/models - 避免用
interface{}或map[string]interface{}作响应体字段——swag 无法推导结构，生成空 schema - 中文注释本身没问题，但若
go.mod模块路径含中文或空格，可能导致文件解析失败，建议项目路径纯英文
docs/docs.go 编译失败或 404
生成的 docs/docs.go 是硬编码 import 路径的桥接文件，一旦模块名、路径、大小写不一致，就会报 cannot find module 或 404。
- 执行
swag init前，确认go mod init的模块名和你代码中实际 import 的路径完全一致（包括大小写） - 必须在模块根目录（即含
go.mod的那层）执行命令，否则docs.go里的 import 路径会错位 -
/swagger/index.html404 是因为 swag 只生成静态资源，没自动注册路由；你得手动调用ginSwagger.WrapHandler(docs.SwaggerInfo)并挂到对应 path - 如果改过结构体字段但没重跑
swag init，docs.go仍引用旧字段名，会导致编译失败
最容易被忽略的是：handler 函数上方的注释必须紧邻函数声明，不能隔空行；@Router 路径必须和实际 r.GET("/xxx", handler) 完全一致；大小写敏感，@success 不等于 @Success。
