Golang怎么生成Swagger文档_Golang如何用swag自动生成API接口文档【教程】-Golang-PHP中文网

swag init 找不到 handler 的根本原因是默认仅扫描当前目录同包的 .go 文件；需用 -g 指定入口文件以递归解析 import 依赖，且注释格式、包路径、模块名必须严格匹配规范。

golang怎么生成swagger文档_golang如何用swag自动生成api接口文档【教程】

swag init 命令为什么找不到 handler 函数

根本原因不是代码写得不对，而是 swag init 默认只扫描当前目录及其子目录下的 .go 文件，且要求这些文件属于同一个 Go 包（即 package 声明一致）。如果你的路由注册和 handler 分散在不同包（比如 main 和 handler），但没显式告诉 swag 扫描路径，它就直接跳过。

运行 swag init -g main.go，强制指定入口文件，swag 会顺着 import 关系递归解析依赖包
确保所有含 Swagger 注释的 handler 文件都属于被 main.go 直接或间接 import 的包，不能是孤立的 package handler 却没被引用
别把 handler 放在 _test.go 文件里——swag 默认忽略测试文件
Windows 下路径含空格或中文可能导致解析失败，建议项目路径纯英文、无空格

注释写法必须严格匹配 swag 要求的格式

swag 不解析任意注释，只认特定前缀 + 固定字段名。少一个 @、字段名拼错（比如写成 @success 而非 @Success）、冒号后多空格，都会导致该接口不进文档。

Alibabacloud Sdk Client Initialization For Golang

初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。

下载

// @Summary 创建用户 —— 必须顶格，前面不能有空格或其它字符
// @Param user body models.User true "用户信息" —— body 后必须跟结构体全名（含包名，如 models.User），不能只写 User
// @Success 200 {object} models.User —— 返回类型也需带包名；如果返回指针，要写 *models.User
不要混用 @produce json 和 @Produce json，大小写敏感，官方示例全用大写首字母

生成的 docs/docs.go 无法编译：import 路径冲突

swag 生成的 docs/docs.go 里硬编码了 import "your-project-name/docs"，一旦你项目模块路径（go.mod 第一行）和本地文件路径不一致，就会报 cannot find module 或循环 import 错误。

初始化前先确认 go mod init 的模块名和你实际 import 的路径完全一致（包括大小写）
执行 swag init -o ./docs 时，确保当前目录是模块根目录（即有 go.mod 的那层）
如果项目用了 vendor，加 --parseVendor 参数，否则 swag 看不到 vendor 里的结构体定义
修改过结构体字段后忘记重新 run swag init，会导致 docs.go 里引用的旧字段名编译失败

启动服务后 /swagger/index.html 404

swag 生成的是静态资源，不是自动注册路由。你得手动把 docs.SwaggerInfo 挂到 HTTP 路由上，而且路径前缀必须和前端请求的 URL 对得上。

用 http.ServeFile 是错的——它不支持 SPA 路由（比如刷新 /swagger/xxx 会 404）
正确做法：导入 github.com/swaggo/http-swagger，然后 r.Get("/swagger/*any", httpSwagger.WrapHandler)（Gin）或类似适配器
注意 /swagger/*any 中的 *any 不能漏，这是通配必需语法
如果 API 服务跑在子路径（如 /api/v1），Swagger UI 的 base URL 也要同步改，否则请求 /swagger/doc.json 会 404