Go项目应使用swag工具通过结构化注释自动生成swagger.json及UI，核心是@Summary、@Router、@Param、@Success等注释配合swag init命令，确保结构体导出且带json tag，docs/docs.go被main包导入。
Go 项目里直接手写 OpenAPI spec 几乎不可维护，真正可行的路径是：用结构化注释 + swag 工具自动生成 docs/swagger.json，再配合 httpSwagger 在开发环境暴露 UI。其他方案（如基于反射全自动推导）要么覆盖不全，要么破坏类型安全。
为什么不用 go-swagger 的 annotate 模式？
go-swagger 要求你在每个 handler 上写冗长的 // swagger:route 块，且参数、响应体必须手动映射到 model 定义，稍一改 struct 就得同步改注释——实际项目中极易脱节。而 swag（即 swaggo/swag）只依赖标准 Go doc 注释 + 少量标记，模型定义和业务代码完全共用同一套 struct，改字段名/类型后运行 swag init 就自动更新 schema。
- 它会扫描
type定义，提取 JSON tag、struct 字段注释、嵌套关系，生成准确的components.schemas - 对
gin、echo、net/http都有适配器，无需改路由注册逻辑 - 不侵入运行时，纯编译前生成，无性能开销
必须加的注释字段有哪些？
swag 不是“零配置”，但只需在关键位置补 3 类注释：API 入口函数顶部的元信息、请求体参数声明、响应结构体标记。漏掉任一环节，对应部分就会缺失或变成 object{}。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 入口函数上方用
// @Summary、// @Description、// @Tags描述接口用途和分组 - 用
// @Param显式声明 path/query/header 参数，例如// @Param id path int true "user ID" - 请求体（
body）和响应体（200等状态码）必须用// @Success 200 {object} UserResponse或{array} []User，且UserResponse必须是已定义的顶层 struct（不能是匿名 struct 或内嵌在函数里的类型） - 如果响应是标准错误格式，用
// @Failure 400 {object} ErrorResponse并确保该 struct 也在扫描范围内
常见生成失败原因与修复
运行 swag init 后没生成 docs/ 或字段为空，90% 是路径或类型可见性问题。
-
swag init -g cmd/myapp/main.go中的入口文件路径必须能静态解析所有 handler 和 model —— 如果你的 handler 分散在多个包，需用-d指定根目录，例如swag init -d ./... - struct 必须是大写首字母（即 exported），否则
swag扫描不到其字段；json:tag 若含omitempty不影响生成，但若字段没 tag，默认按 Go 字段名转 camelCase - 嵌套 struct 自动展开，但如果用了
map[string]interface{}或interface{}，生成结果会是空{}，应改用具体 struct 或加// @Schema注释引导 - 使用
gin.Context时，别在注释里写@Param ctx——ctx不是 HTTP 参数，swag会忽略，也不该出现在 spec 中
最易被忽略的是：生成后的 docs/docs.go 必须被 main 包 import，否则 httpSwagger.Handler() 加载不到资源；还有就是 @ID 字段虽然可选，但建议每个接口都加唯一 ID（如 // @ID GetUserByID），否则 Swagger UI 在多版本或重载时可能混淆同路径不同方法的文档。
