本文介绍如何通过 goswagger 工具为 Gin 项目手动注释并生成符合 OpenAPI 2.0 规范的 swagger.json，解决 Gin 原生不支持 Swagger 文档自动生成的问题。
本文介绍如何通过 goswagger 工具为 gin 项目手动注释并生成符合 openapi 2.0 规范的 `swagger.json`，解决 gin 原生不支持 swagger 文档自动生成的问题。
Gin 本身是一个轻量级 Web 框架，并未内置 OpenAPI（Swagger）文档生成能力，其稳定版本确实不提供自动解析路由并输出 swagger.json 的功能。因此，直接运行 swag init 或 go generate 后得到空 "paths": {} 的结果是预期行为——因为 Gin 的路由注册是动态的（运行时 engine.GET/POST 等调用），静态分析工具无法自动推导。
✅ 正确方案：使用 goswagger（官方推荐的 Go OpenAPI 工具链），配合规范的 GoDoc 注释，实现声明式 API 文档生成。
✅ 步骤概览
-
安装 goswagger CLI（需 Go 1.16+）：
# macOS (Homebrew) brew tap go-swagger/go-swagger brew install go-swagger
Linux / Windows (binary download)
curl -o ./swagger -L https://www.php.cn/link/3c26496c57764077d8ef078e75185ba3 chmod +x ./swagger sudo mv ./swagger /usr/local/bin/
2. **在 `main.go` 或 API 入口文件顶部添加 Swagger 根注释**（必须）： ```go // Package api Gin-based REST API with Swagger docs // @title User Management API // @version 1.0 // @description This is a sample server 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
-
为每个 Handler 添加结构化注释（关键！）：
// CreateUser creates a new user // @Summary Create a new user // @Description Creates a user with given details; returns created user with ID // @Tags users // @Accept json // @Produce json // @Param user body models.User true "User object to create" // @Success 201 {object} models.User // @Failure 400 {object} models.ErrorResponse // @Router /users [post] func CreateUser(c *gin.Context) { var user models.User if err := c.ShouldBindJSON(&user); err != nil { c.JSON(400, models.ErrorResponse{Message: "Invalid request"}) return } // ... save logic c.JSON(201, user) }
⚠️ 注意：@Router 行必须与 Gin 实际注册的路径完全一致（如 r.POST("/users", CreateUser) → @Router /users [post]），且动词小写。
-
生成 swagger.json：
swagger generate spec -o ./docs/swagger.json --scan-models
✅
--scan-models确保自动提取结构体定义（models.User等）到definitions；若模型分散，可指定目录：-m ./models （可选）集成 Swagger UI
将生成的swagger.json通过 Gin 提供静态服务，或使用swaggo/files+swaggo/gin-swagger：
import "github.com/swaggo/gin-swagger"
import "github.com/swaggo/files"
// 在路由设置中
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))⚠️ 常见问题与注意事项
- ❌ 不要依赖
swag init（来自swaggo/swag）：它是为swaggo/gin-swagger设计的轻量替代，但对 Gin 路由识别有限，易产生空 paths； - ✅ 必须保证所有
@Router路径与 Ginr.XXX()注册路径字面量一致（含前缀、斜杠）； - ✅ 结构体字段需有
jsontag 才能被goswagger正确映射为 schema； - ✅ 使用
// @Security ApiKeyAuth等认证声明时，需同步在@securityDefinitions中定义； - ? 修改注释后务必重新运行
swagger generate spec，该命令不监听文件变更。
✅ 总结
无需更换框架。Gin 与 goswagger 是成熟组合：Gin 专注 HTTP 处理，goswagger 专注 OpenAPI 声明与生成。通过严谨的 GoDoc 注释，你既能保持 Gin 的简洁与性能，又能产出专业、可交互、可验证的 API 文档。坚持“注释即契约”原则，让文档与代码真正同步演进。
