Go语言框架API文档自动生成 Go语言开发效率【提升】-Golang-PHP中文网

go语言api文档自动生成依赖swag工具，需在项目根目录执行go install安装、handler函数上方紧贴写全@summary/@router等注释、类型引用带包名、结构体字段加json tag，并手动注册/swagger路由。

go语言框架api文档自动生成 go语言开发效率【提升】

Go 语言本身不提供 API 文档自动生成能力，真正起作用的是工具链——swag 是目前最稳定、兼容性最好、社区验证最充分的选择。它不依赖运行时反射，只靠静态解析注释，生成标准 OpenAPI 3.0 的 swagger.json，再配合 UI 渲染即可交付可用文档。

swag init 报 cannot find main.go 或漏掉接口，基本是环境或结构没对齐：

必须在项目根目录执行（即包含 main.go 或 server.go 的目录），不是 cmd/ 或 internal/ 子目录
go install github.com/swaggo/swag/cmd/swag@latest —— 注意用 go install，go get 已被弃用
每个 HTTP handler 函数（如 Login）上方必须紧贴声明写完整注释块，中间不能有空行
注释里所有类型引用（如 {object} model.User）必须带包名，且该包已在文件顶部 import

swag 对注释语法极其敏感，常见失效点集中在参数和响应定义：

Go语言（Golang）1.26.0

Go语言（Golang）1.26.0版本提供 Go 官方 Windows amd64 MSI 安装包下载入口，版本号 1.26.0，可用于旧项目维护、兼容性测试和指定版本开发环境配置。

下载

// @Param id path int true "user ID" ✅ 路径参数；// @Param id query string true "user ID" ✅ 查询参数；但写成 string "user ID" 或漏掉 true 就会丢参数
// @Success 200 {object} model.User ✅；// @Success 200 {object} User ❌（缺包名）；// @Success 200 {array} model.User ✅；// @Success 200 {array} ❌（没指定元素类型）
结构体字段若要出现在请求/响应示例中，必须带 json tag，例如 Name string `json:"name"`；否则 swag 无法推导字段名和序列化行为

生成 docs/ 目录只是第一步，不注册路由，访问 /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"))))