swag 是 go 最成熟的 openapi 文档生成工具，通过解析源码注释生成 swagger.json；需在项目根目录执行 swag init，handler 函数须带完整注释块且紧贴声明，结构体字段需 json tag，gin/echo 需手动注入 swagger ui 路由。
Go 语言本身不内置 API 文档生成器，但 swag 是目前最成熟、与 Go 原生风格兼容性最好的方案——它通过解析源码中的特定注释（而非反射或运行时分析），生成符合 OpenAPI 3.0 规范的 swagger.json，再交由 Swagger UI 渲染。别指望 godoc 或 go doc 能输出 REST API 文档，它们只管包/函数说明。
用 swag init 生成 swagger.json 的前提条件
必须在项目根目录（即包含 main.go 或 server.go 的目录）执行 swag init；否则会报 cannot find main.go 或扫描不到 handler 函数。
-
swag命令行工具需先安装：go install github.com/swaggo/swag/cmd/swag@latest（注意：不是go get，新版 Go 已弃用） - 所有 HTTP handler 函数（如
GetUsers）必须有完整的// @Summary、// @Success等注释块，且注释必须紧贴函数声明上方，中间不能有空行 - 结构体字段若要出现在请求/响应示例中，需带
jsontag，例如Name string `json:"name"`；否则swag无法推导字段名和类型 - 如果用的是 Gin、Echo 或 net/http，
swag init都能识别，但路由注册方式不影响解析——它只看函数签名和注释，不分析r.GET()这类调用
常见注释写法与易错点
swag 对注释格式极其敏感，一个标点错误就会导致字段丢失或生成失败。比如 @Param 后必须跟参数名、类型、位置（path/query/body）、是否必需，缺一不可。
-
// @Param id path int true "user ID"✅ 正确：路径参数id，类型int，位置path -
// @Param id query string true "user ID"✅ 查询参数，类型写string，不是string加引号 -
// @Success 200 {object} model.User✅ 响应体是结构体指针或值均可，但model.User必须可被导入（即所在包已import） - 错误写法：
// @Success 200 {object} User❌ 没带包名，swag找不到定义；或写成{array}却没指定元素类型，如{array} model.User才对
集成到 Gin/Echo 服务并暴露 Swagger UI
生成 docs/ 目录后，需手动把文档路由注入 HTTP 服务。这步不能跳过，否则访问 /swagger/index.html 会 404。
- Gin 用户：导入
github.com/swaggo/gin-swagger和github.com/swaggo/files，然后加一行r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) - Echo 用户：用
github.com/swaggo/echo-swagger，调用e.GET("/swagger/*", echoSwagger.WrapHandler) - net/http 用户：直接用
http.FileServer挂载docs/目录，但注意路径映射——http.Handle("/swagger/", http.StripPrefix("/swagger/", http.FileServer(http.Dir("./docs")))) - 启动服务前务必确保
docs/docs.go已生成（swag init自动创建），否则运行时报undefined: docs.SwaggerInfo
真正麻烦的不是生成文档，而是保持注释与代码同步。比如改了结构体字段但忘了更新 @Success 注释里的类型，或者新增了 query 参数却漏写 @Param，swag 不会报错，只会静默忽略——最终 UI 上看不到那个字段。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
