swagger页面空白或404，90%是因为swag init未生成docs/docs.go或import _ "your-module-name/docs"导入路径错误；需确保swag正确安装、注释含@title/@version、结构体字段导出且带json tag、路由挂载为/swagger/*any并重启服务。
Swagger页面空白或404，90%是因为swag init没生成docs/docs.go，或_ "your-module-name/docs"这行导入写错了。
swag CLI安装失败或命令找不到
Go 1.16+必须用go install，go get装不上可执行文件：
-
go install github.com/swaggo/swag/cmd/swag@latest（推荐带版本号，如@v1.17.0） - 装完立刻跑
swag -version验证；报command not found就说明$GOPATH/bin没进系统PATH - Windows下常见路径是
C:\Users\{user}\go\bin，macOS/Linux一般是$HOME/go/bin，手动加进PATH再开新终端
swag init后/swagger/index.html 404或空白
核心问题只有两个：文档没生成，或生成了但没被加载。先检查docs/docs.go是否存在、是否为空：
- 运行
swag init -d ./显式指定根目录（尤其当main.go不在项目根目录时） - 确保
main.go顶部有完整全局注释块，且必须含// @title和// @version两行，缺一不可 -
import语句里必须写_ "your-module-name/docs"——这个your-module-name要和go.mod第一行module xxx完全一致，不能写./docs或docs - 如果
docs/docs.go存在但内容为空，大概率是注释格式错：比如//@title少空格、换行符是\r\n而非\n、用了中文标点
接口注释写不对导致参数不显示或类型错
注释里的@Param必须严格匹配实际传参方式，否则Swagger UI里根本看不到字段：
-
@Param id path int true "用户ID"→ 对应/users/{id}这种路由，id得是gin.Param("id")取的 -
@Param username query string true "用户名"→ 对应?username=xxx，代码里要用c.Query("username") -
@Param user body models.User true "用户对象"→models.User必须是已定义结构体，且包名不能省，body不能写成json或form -
@Success 200 {object} models.UserResponse里的models.UserResponse也得是完整包路径，否则生成的swagger.json里会变成{}
路由注册后Swagger页面加载慢或报错
不是性能问题，而是静态资源加载路径或中间件冲突：
-
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))必须放在所有router注册之后，否则可能被其他中间件拦截 - 别用
ginSwagger.URL(".../doc.json")自定义地址——新版gin-swagger已弃用该方式，直接用WrapHandler即可 - 如果项目启用了HTTPS重定向或CORS中间件，确认
/swagger/*any路径没被过滤或重写 -
swaggerFiles.Handler来自github.com/swaggo/files，不是swaggerFiles包名——导入时alias成swaggerFiles只是习惯，实际包名是files
最常被忽略的是：每次改了注释，必须重新跑swag init，然后重启服务；docs/docs.go是编译期注入的，热重载不生效。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
