gin默认不带swagger ui因其是轻量级框架，不内置api文档功能；需手动集成swag工具生成docs、导入docs包并注册路由，三者缺一不可。
为什么 Gin 默认不带 Swagger UI？
Gin 本身是轻量级 Web 框架，不内置 API 文档功能。你看到的 swagger.json 或交互式 UI，必须手动接入第三方库（如 swag）并配合生成和路由注册。直接写 @Summary 注释不会自动生效，不运行 swag init 就没文件，不注册路由就打不开 /swagger/index.html。
-
swag是最常用方案，它扫描 Go 源码里的 Swagger 注释，生成符合 OpenAPI 3.0 规范的docs/docs.go - 生成的
docs包需显式导入，否则gin-swagger找不到静态资源 - 注释必须写在 HTTP handler 函数上方，且函数签名要带
*gin.Context参数，否则swag init会跳过
怎么让 swag init 正确识别你的 handler？
常见错误是注释位置不对、函数没暴露、或用了闭包/匿名函数。Swag 只解析导出的（首字母大写）、接收 *gin.Context 的函数。
- 确保 handler 是包级函数，不是方法或闭包：
func GetUser(c <em>gin.Context)</em>✅，r.GET("/user", func(c gin.Context){...})❌ - 注释块紧贴函数声明上方，中间不能有空行
- 使用标准 Swagger 字段，比如
@Summary、@Param、@Success，拼写错误（如@Sumary）会导致字段丢失 - 如果项目有多个
main.go或多模块，用-g指定入口文件：swag init -g cmd/server/main.go
示例正确写法：
// @Summary 获取用户信息
// @Param id path int true "用户ID"
// @Success 200 {object} model.User
// @Router /users/{id} [get]
func GetUser(c *gin.Context) {
// ...
}
如何把 Swagger UI 嵌入 Gin 路由？
不能只靠 swag init，还得在代码里注册路由并启用静态服务。
- 必须导入生成的
docs包（即使没显式调用），否则ginSwagger.WrapHandler没数据源 - 路由路径默认是
/swagger/*any，但前端访问的是/swagger/index.html，别漏掉index.html - 如果 Gin 启用了
gin.ReleaseMode，Swagger UI 仍可访问；但开发时建议保留，方便调试
关键代码片段：
import _ "your-project/docs" // 注意：下划线导入，触发 docs.init()
<p>// ...</p><p>r := gin.New()
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
</p>
调试时点“Try it out”没反应或 404？
多数问题出在请求路径、参数绑定或 CORS 上。
- 检查浏览器控制台：如果报
Failed to fetch，大概率是后端没开 CORS，加cors.Default()中间件 -
@Param类型写错会导致参数不注入：path 参数用path，query 用query，body 用body，写成formData却没配@Accept multipart/form-data就会失败 - Swagger UI 发送的是真实 HTTP 请求，所以 handler 里所有校验逻辑（如 JWT 解析、数据库连接）都会执行——别在文档页测试未就绪的接口
- 修改注释后必须重新运行
swag init，否则 UI 不更新
路径匹配容易被忽略：Gin 路由是 /api/v1/users，但你在 @Router 里写了 /users，UI 发请求就会 404。要么统一前缀，要么在 @Router 中写全路径。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
