Go语言如何生成OpenAPI_Go语言OpenAPI文档教程【收藏】-Golang-PHP中文网

swag是go项目生成openapi文档最稳定轻量的工具，仅依赖源码注释、不依赖运行时，需在项目根目录执行swag init，注释须紧贴函数声明且严格匹配json tag，openapi 3.0需显式声明@openapi 3.0.0。

go语言如何生成openapi_go语言openapi文档教程【收藏】

swag 是目前 Go 项目里生成 OpenAPI 文档最稳定、最轻量的选择——它不依赖运行时，只靠源码注释就能产出 swagger.json，且能直接对接 Swagger UI。别指望 godoc 或 go doc 能干这事，它们根本不处理 HTTP 路由和请求/响应结构。

执行 swag init 前，确保你在包含 main.go 或 server.go 的目录下。否则会报 cannot find main.go 或扫描不到 handler 函数。

swag init -g ./cmd/server/main.go 这种指定路径的方式仅在 v1.8+ 支持，但仍有风险：若 main.go 里没 import handler 所在包，函数仍会被忽略
推荐做法：把 swag init 当作构建前一步，在 Makefile 或 CI 脚本里固定为 cd $(PROJECT_ROOT) && swag init -o ./docs
生成的 docs/swagger.json 应该提交进 Git——它是文档事实来源，不是中间产物

swag 不推导结构体字段，只读 json: tag。比如这个字段：Name string `json:"name"`，如果写成 `json:"Name"` 或漏掉 tag，@Success 200 {object} model.User 就不会显示 name 字段。

@Param id path int true "user ID"：路径参数类型写 int，不是 int64 或 "int"
@Success 200 {array} model.User：必须带 {array} + 元素类型，不能只写 {array}
@Security ApiKeyAuth 要生效，得先有对应 @securityDefinitions.apiKey ApiKeyAuth，且位置、名称、in 字段全对上

即使你用的是最新版 swag（v1.17+），默认仍输出 Swagger 2.0 格式。要得到真正的 OpenAPI 3.0，必须在 main.go 文件顶部第一行非空注释写：

Go语言（Golang）1.26.0

Go语言（Golang）1.26.0版本官方下载，版本号 1.26.0，适合旧项目维护、兼容性测试和指定版本开发环境搭建。

下载

// @openapi 3.0.0

注意：不能缩进、不能有空格、不能放在函数内部或注释块中间。

检查生成结果：打开 docs/swagger.json，第一行必须是 "openapi": "3.0.0"，不是 "swagger": "2.0"
认证方式升级：旧的 @securityDefinitions apiKey 已失效，改用 @securityDefinitions.apiKey ApiKeyAuth + @in header + @name Authorization
Swagger UI v4+ 才能正确渲染 securitySchemes 和 oneOf，v3 会静默丢弃

生成 docs/ 目录只是第一步。swag init 不会自动注册 HTTP 路由，不挂载就访问不到 /swagger/index.html。

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 挂载，但注意路径映射——http.Handle("/swagger/", http.StripPrefix("/swagger/", http.FileServer(http.Dir("./docs"))))

最容易被忽略的是：所有 handler 函数的注释块必须紧贴函数声明上方，中间不能有任何空行。哪怕只多一个换行，swag 就认为注释不属于该函数，字段和响应体全部丢失。