swag是当前Go项目唯一稳定落地的OpenAPI文档生成方案，但需满足硬性条件：必须用-g指定入口文件、-d显式扫描分散路径、handler函数需导出且紧贴@Summary/@Router注释、@Param/@Success类型仅限基础类型或@Model声明的struct、结构体字段须导出并带json tag。
用 swag 是当前 Go 项目里唯一能稳定落地的 OpenAPI 文档自动化生成方案，它不依赖运行时、不破坏类型安全、改注释即更新文档——但必须满足几个硬性条件，否则生成结果为空或字段全丢。
swag init 扫不到接口？检查扫描路径和入口文件
执行 swag init 后 docs/swagger.json 中 paths 为空，或 UI 显示首页但没接口列表，90% 是扫描范围配置错误。
- 默认只扫描当前目录及子目录下属于同一 Go module 的
.go文件；若 handler 分散在internal/handler、pkg/api等路径，必须显式指定：swag init -d internal/handler -d pkg/api - 入口文件（如
cmd/app/main.go）要用-g指定：swag init -g cmd/app/main.go，否则跨包注册的路由逻辑可能被跳过 - 被扫描的文件不能是
package main（除非它真包含r.GET()这类注册），推荐把路由逻辑单独放在package router或package api - 所有 handler 文件必须有合法
package xxx声明，且不能含语法错误，否则整文件被静默跳过
@Param 和 @Success 写错类型？swag 不认 Go 类型系统
swag 的类型解析器与 Go 编译器不一致：它只识别基础类型名（string、int、bool、float64）和已用 // @Model 显式声明过的 struct。
Alibabacloud Sdk Client Initialization For Golang
下载
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
-
@Param id path string true "用户ID"✅ —— 路径/查询/请求头参数只能写string，别写int64或uuid.UUID -
@Param user body model.User true "用户信息"✅ —— 请求体（in: body）必须指向一个已定义的 struct，且该 struct 上方需有// @Model注释 -
@Success 200 {object} model.UserResponse✅ —— 结构体必须导出（首字母大写），字段必须带json:"xxx"tag，否则字段不会出现在 schema 中 - 数组参数不能简写为
type: []string，而应写为：@Param ids query array true "ID列表" collectionFormat:multi items.type:string
中文乱码、响应体显示 “object”、字段全空？检查三个硬性条件
文档加载后中文变 \u4f60\u597d，或点开响应 schema 全是空对象，大概率不是配置问题，而是代码层面没满足 swag 的硬性要求：
立即学习“go语言免费学习笔记（深入）”；
-
swag init必须在项目根目录执行（即包含go.mod的目录），否则无法正确解析 module 路径 - 结构体字段必须导出（首字母大写）且带
json:tag；若字段写成Name string `json:"Name"`或漏掉 tag，@Success就不会显示该字段 - OpenAPI 3.0 输出需显式声明：
// @openapi 3.0.0必须放在main.go文件顶部第一行非空注释，不能缩进、不能有空格、不能在函数内部
最容易被忽略的是：生成的 docs/ 目录必须手动导入到 main 包中，否则服务启动后访问 /swagger/index.html 会 404；另外，Docker 构建镜像时必须显式 COPY docs/ docs/，IDE 有时也会忽略该目录。
