Gin + Swagger

 

Gin 集成 Swagger , GitHub - swaggo/gin-swagger: gin middleware to automatically generate RESTful API documentation with Swagger 2.0.

1. 下载 Swagger
   1. 　　

      go install  github.com/swaggo/swag/cmd/swag@latest

2. 生成 swag.exe, 在 GOPATH / bin

   1. go install github.com/swaggo/swag/cmd/swag@latest
      

   2. 

3. 在项目根目录，打开终端，执行

   1. swag init
      

   2. 执行完之后，会生成如下文件

   3. 

4. 下载 gin-swagger

   1. go get -u github.com/swaggo/gin-swagger
      go get -u github.com/swaggo/files
      

5. Import

   1. // 这三种不可少
      import (
      	_ "Gin_Study/docs"
      	swaggerfiles "github.com/swaggo/files"
      	ginSwagger "github.com/swaggo/gin-swagger"
      )
      

      　　

   2.  

      在路由定义swagger 的路径

      1. 	// 定义swagger 的路径，首页是 /swagger/index.html
         	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
         

         　　

         　　　　
6. Full Code

   1. 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")
      
      }
      
      

7. 运行Gin，并在浏览器访问 Swagger UI
   

   1. 

      

8. 具体的注释参数，还要参考 Git Hub 里面的内容，每次修改注释后，都要执行 

   1. swag init
      

9. 接口文档，登录验证（基本认证（Basic access authentication）），这里搭配 gin.BasicAuth，当然最后项目部署的时候，也可以通过 Nginx 实现这部分功能
   
   1. 　　

      	// swagger Basic Auth
      	swaggerGroup := r.Group("swagger", gin.BasicAuth(gin.Accounts{
      		"test": "test",
      	}))
      	{
      		swaggerGroup.GET("*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
      	}
      

      

       用户名 和 密码 在代码里面 gin.Accounts , 可以配置多个

   2. 

       

10. 不显示 models
    
    // swaggerGroup.GET("*any", ginSwagger.WrapHandler( // swaggerfiles.Handler, // // don't show models // ginSwagger.DefaultModelsExpandDepth(-1), // ))

    	// // 如果有设置环境变量DISABLE_SWAGGER，接口文档就会是404
    	swaggerGroup.GET("*any", ginSwagger.DisablingCustomWrapHandler(
    		&ginSwagger.Config{
    			URL:          "doc.json",
    			DocExpansion: "list",
    			InstanceName: "",
    			Title:        "Swagger UI",
    			// don't show models
    			DefaultModelsExpandDepth: -1,
    			DeepLinking:              true,
    			PersistAuthorization:     false,
    			Oauth2DefaultClientID:    "",
    		},
    		swaggerfiles.Handler,
    		"DISABLE_SWAGGER",
    	))
    

小结：

• Swagger 其实就是通过注释，生成对应的API。如果只改了代码，而不修改注释，Swagger 是不会发生变化的，从这个角度出发，程序猿既要维护代码，又要维护注释了，这算不算给自己挖了一个坑？？？