gin 默认不生成 openapi 文档，因其本身是极简框架，不内置规范生成逻辑，也不解析注释；需借助 swag 工具在编译期扫描注释生成 docs，再通过 gin-swagger 集成 ui。
为什么 Gin 默认不生成 OpenAPI 文档？
Gin 本身是极简 HTTP 路由框架，gin.Engine 不内置 OpenAPI（Swagger）规范生成逻辑，也不会自动解析 @Summary 或 @Param 这类注释。你看到的“Gin + Swagger”方案，实际是靠第三方工具在编译期或运行时补全元数据，不是 Gin 自身能力。
常见误区是直接给 gin.HandlerFunc 加注释就以为能出文档——不行，Gin 不读这些注释；更不能指望 gin.Default() 启动后访问 /swagger/index.html 就自动有界面——那得你自己集成前端静态资源和路由。
用 swag init 生成 docs/ 的关键前提
swag init 是最主流的 Go OpenAPI 文档生成方式，但它依赖源码中的特定注释格式，并且只扫描当前目录及子目录下带 .go 后缀的文件。它不分析 Gin 的 GET/POST 调用链，而是靠你手写注释来描述接口。
- 必须在 main 包或 API 入口文件顶部加
// @title My API、// @version 1.0等全局元信息 - 每个 handler 函数上方要写完整注释块，包含
// @Summary、// @Success 200 {object} model.User、// @Router /users [get] -
swag init生成的docs/docs.go必须被 import，否则docs.SwaggerJSON等变量不可见 - 如果用 Go Modules，确保
swag版本与 Gin 版本兼容（v1.8+ 推荐用 swag v1.8.10+，旧版对泛型支持弱）
把 docs 注册进 Gin 路由的正确姿势
别直接 router.Static("/swagger", "./docs") ——这只会暴露 JSON 文件，没 UI。真正要的是 Swagger UI 页面，它需要加载 swagger.json 并渲染交互界面。
标准做法是用 gin-swagger 中间件，它封装了静态资源服务和 JSON 路由：
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
import "github.com/swaggo/gin-swagger"
import "github.com/swaggo/files"
// 在 router 初始化后
router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
注意三点：
-
/*any是 Gin 的通配符写法，不是正则，必须这么写才能匹配/swagger/下所有路径 -
swaggerFiles.Handler来自github.com/swaggo/files，不是本地docs/目录 - 如果你改过
swag init -o输出路径（比如输出到api/docs），docs.SwaggerJSON仍会从默认位置加载，除非你手动修改docs/doc.go里的doc变量指向新路径
接口返回结构体嵌套时文档常漏字段
当 handler 返回的是嵌套结构体（如 Response{Data: User{ID: 1, Name: "a"}}），swag 默认只解析顶层类型，不会递归展开 Data 字段指向的 User。结果是 Swagger 页面里 Response.Data 显示为 object，点不开详情。
解决方法只有显式标注：
- 在
@Success注释中写全路径：// @Success 200 {object} Response{Data=model.User} - 或给
User结构体加// swagger:response UserResponse注释块，并在@Success中引用：// @Success 200 {object} UserResponse - 避免使用匿名结构体返回：
c.JSON(200, struct{Msg string}{Msg: "ok"})—— swag 根本无法为其生成 schema
这一步漏掉，前端同学点开文档看不清字段类型，基本等于没文档。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
