本文介绍如何在 Go + Gin-Gonic 项目中手动构建符合 OpenAPI 2.0 规范的 swagger.json，重点解决因 Gin 本身不内建 Swagger 支持而导致路径为空的问题，推荐使用 goswagger 工具配合结构化注释自动生成。
本文介绍如何在 go + gin-gonic 项目中手动构建符合 openapi 2.0 规范的 swagger.json，重点解决因 gin 本身不内建 swagger 支持而导致路径为空的问题，推荐使用 goswagger 工具配合结构化注释自动生成。
Gin-Gonic 是一个轻量、高性能的 Web 框架，但它本身不提供运行时 Swagger UI 或自动 API 文档生成功能（截至 v1.x 稳定版）。因此，直接调用 swag init 或期望 Gin 自动扫描路由并填充 paths 字段是不可行的——这也是你看到 "paths": {} 的根本原因。
✅ 正确方案：使用 goswagger（独立于 Gin 的成熟 OpenAPI 工具链），通过 Go 源码注释 + 命令行生成方式构建 swagger.json。
✅ 步骤详解
1. 安装 goswagger CLI
# macOS (Homebrew) brew tap go-swagger/go-swagger brew install go-swagger # Linux / Windows（二进制下载） curl -o swagger -L https://github.com/go-swagger/go-swagger/releases/download/v0.31.0/swagger_linux_amd64 chmod +x swagger sudo mv swagger /usr/local/bin/
2. 在 main.go 或 API 入口文件顶部添加 OpenAPI 元信息注释
// Package api Gin REST API // @title User Management API // @version 1.0 // @description This is a sample API for user CRUD operations. // @termsOfService http://swagger.io/terms/ // @contact.name API Support // @contact.url http://www.swagger.io/support // @contact.email support@swagger.io // @license.name Apache 2.0 // @license.url http://www.apache.org/licenses/LICENSE-2.0.html // @host localhost:8080 // @BasePath /api/v1 // @securityDefinitions.apikey ApiKeyAuth // @in header // @name Authorization // @externalDocs.description OpenAPI Documentation // @externalDocs.url https://swagger.io/docs/ package main
⚠️ 注意：所有
@xxx注释必须位于 package 声明上方，且以//开头，无空行隔断。
3. 为每个 HTTP Handler 添加详细接口注释
以 GET /api/v1/users 为例：
// ListUsers godoc
// @Summary List all users
// @Description Get a list of users with optional pagination
// @Tags users
// @Accept json
// @Produce json
// @Param page query int false "Page number (default: 1)"
// @Param limit query int false "Items per page (default: 10)"
// @Success 200 {array} User
// @Failure 500 {object} errorResponse
// @Router /users [get]
func ListUsers(c *gin.Context) {
// 实现逻辑...
}4. 运行生成命令
确保当前目录包含上述注释的 Go 文件（如 main.go）：
swag init -g main.go -o ./docs
该命令将：
- 扫描所有
// @xxx注释； - 解析结构体定义（需额外注释
// swagger:response/// swagger:model）； - 输出
docs/swagger.json和docs/swagger.yaml（含完整paths和definitions）。
5. （可选）集成 Swagger UI
将生成的 docs/ 目录静态托管，或使用 gin-contrib/swagger 快速嵌入 UI：
import "github.com/swaggo/files"
r := gin.Default()
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))? 关键注意事项
- ❌ 不要依赖 Gin 自动推导路由：
gin.Engine.Routes()无法被goswagger解析，必须显式注释每个 handler； - ✅ 结构体模型需标注（尤其用于请求/响应体）：
// @swagger:model User type User struct { ID uint `json:"id"` Name string `json:"name"` } - ? 每次修改接口或参数后，务必重新执行
swag init； - ? 若项目模块化（handlers 分散在多包），需用
-o指定统一输出目录，并确保swag init能访问全部相关.go文件。
✅ 总结
无需更换框架——Gin 与 goswagger 是业界广泛验证的黄金组合。它不侵入业务逻辑，不增加运行时开销，且文档与代码共生，保障一致性。只要遵循规范注释，即可稳定产出标准 swagger.json，无缝对接 Swagger UI、Postman、OpenAPI Codegen 等生态工具。
? 提示：可将
swag init加入Makefile或 CI 流程，实现文档即代码（Documentation as Code）。
