Gin + Swagger
Gin 集成 Swagger , GitHub - swaggo/gin-swagger: gin middleware to automatically generate RESTful API documentation with Swagger 2.0.
- 下载 Swagger
-
go install github.com/swaggo/swag/cmd/swag@latest
-
- 生成 swag.exe, 在 GOPATH / bin
-
go install github.com/swaggo/swag/cmd/swag@latest
-
-
- 在项目根目录,打开终端,执行
-
swag init
- 执行完之后,会生成如下文件
-
-
- 下载 gin-swagger
-
go get -u github.com/swaggo/gin-swagger go get -u github.com/swaggo/files
-
- Import
-
// 这三种不可少 import ( _ "Gin_Study/docs" swaggerfiles "github.com/swaggo/files" ginSwagger "github.com/swaggo/gin-swagger" )
-
-
// 定义swagger 的路径,首页是 /swagger/index.html r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
-
-
- Full Code
-
package main import ( _ "Gin_Study/docs" "net/http" "github.com/gin-gonic/gin" swaggerfiles "github.com/swaggo/files" ginSwagger "github.com/swaggo/gin-swagger" ) // @Summary ping example // @Schemes // @Description do ping // @Tags example // @Accept json // @Produce json // @Success 200 {string} Helloworld // @Router /v1/ping [get] func v1Pong(ctx *gin.Context) { ctx.JSON(http.StatusOK, gin.H{"message": "hello"}) } // @title Swagger Example API // @version 1.0 // @description Gin Swagger 测试 func main() { // gin.SetMode(gin.ReleaseMode) r := gin.Default() // 定义swagger 的路径,首页是 /swagger/index.html r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler)) r.SetTrustedProxies([]string{"localhost"}) v1 := r.Group("/v1") { v1.GET("/ping", v1Pong) } v2 := r.Group("/v2") { v2.GET("/ping", func(ctx *gin.Context) { ctx.JSON(http.StatusOK, gin.H{"message": "hello"}) }) } r.Run(":8080") }
-
- 运行Gin,并在浏览器访问 Swagger UI
-
- 具体的注释参数,还要参考 Git Hub 里面的内容,每次修改注释后,都要执行
-
swag init
-
- 接口文档,登录验证(基本认证(Basic access authentication)),这里搭配 gin.BasicAuth,当然最后项目部署的时候,也可以通过 Nginx 实现这部分功能
-
// swagger Basic Auth swaggerGroup := r.Group("swagger", gin.BasicAuth(gin.Accounts{ "test": "test", })) { swaggerGroup.GET("*any", ginSwagger.WrapHandler(swaggerfiles.Handler)) }
用户名 和 密码 在代码里面 gin.Accounts , 可以配置多个
-
-
小结:
- Swagger 其实就是通过注释,生成对应的API。如果只改了代码,而不修改注释,Swagger 是不会发生变化的,从这个角度出发,程序猿既要维护代码,又要维护注释了,这算不算给自己挖了一个坑???