go-swagger生成的swagger.json缺少字段注释，因其默认只解析json tag而不读取Go注释，需用// swagger:xxx等特定标记显式声明，且doc.go、handler注释位置、结构体引用等均需严格符合规范。
为什么 go-swagger 生成的 swagger.json 缺少字段注释？
因为 go-swagger 默认只解析结构体字段上的 json tag，不读取 Go 注释。它需要显式标注，比如用 // swagger:response 或在字段前加 // +kubebuilder:validation:Required 这类注释——但这些不是标准 Go 注释，而是 go-swagger 特定的标记语法。
常见错误现象：结构体字段明明写了注释，生成的 OpenAPI schema 里 description 为空；omitempty 导致字段消失，但文档没体现可选性。
- 必须在字段上方紧贴写
// swagger:<em>xxx</em>形式注释（中间不能空行） -
json:tag 中的omitempty不会自动转成 OpenAPI 的"nullable": false，需手动加// +required或// +optional - 嵌套结构体要额外用
// swagger:as:object显式声明，否则可能被当成 primitive
swag CLI 要求 doc.go 必须存在且含 // @title 等元信息
swag（swaggo/swag）靠扫描源码中的特殊注释生成文档，但第一步就卡在找不到入口元数据。它不依赖 main.go，而是找项目根目录下任意 doc.go 文件里的 @title、@version 等标记。
典型报错：ParseComment error in file doc.go : Bad Request: no such file or directory 或生成的 HTML 页标题为空。
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
-
doc.go文件名不能写成docs.go或swagger.go，必须是doc.go - 文件内容至少包含：
// Package api ... // @title My API // @version 1.0 // @description This is a sample server. package api
- 如果项目有多个 module，确保
swag init在正确 module 根目录执行，否则扫描不到 handler 函数
swag init 扫不到 HTTP handler 函数？检查函数签名和注释位置
swag 只识别带特定注释（如 @Summary）且签名符合 func(http.ResponseWriter, *http.Request) 或 func(*gin.Context) 等框架约定的函数。它不分析路由注册逻辑，只看函数本身是否被标注。
现象：生成的 paths 为空，或只有部分接口；Gin 的 c.JSON(200, data) 没触发 response schema 推导。
- 每个 handler 函数上方必须紧贴写
// @Summary ...，且该函数必须在同一 package 内被声明（不能是外部包导入的函数） - Gin 用户需加
// @Router /users [get]和// @Param id path int true "user ID"，参数名、类型、位置（path/query/body）缺一不可 - 返回值若为结构体指针（如
*User），swag 能推导；但若写interface{}或any，schema 就变成object且无字段说明
OpenAPI v3 中 application/json 请求体没生成 schema？
swag 默认只对 POST/PUT 的 body 参数生成 request body schema，但前提是明确标注了 @Param 且 type 是 struct，而不是 string 或 int。
现象：curl -X POST 发送 JSON，文档里却显示 “No parameters” 或 content type 列表为空。
- 必须写：
// @Param user body User true "user info"—— 注意body关键字、结构体名User、第三个字段为true表示 required - 结构体字段若含
json:"name,omitempty"，swag 会自动设"required": false，但前提是字段注释里没加// +required - 如果用了 Gin 的
c.ShouldBindJSON(&u)，确保User结构体已定义且可被 swag 扫描到（非 vendor 内、非 unexported 字段）
跨 package 引用结构体时，swag 不会自动跳转解析，得把结构体定义复制到当前 module，或改用内联注释 // @Schema example={...} 补充描述。
