Gin框架集成swagger过程

安装swagger

1. go get github.com/swaggo/swag/cmd/swag

   在${GOPATH}/bin下生成swag文件

2. 安装依赖包

   go get github.com/gin-gonic/gin
   go get github.com/swaggo/gin-swagger

3. main.go文件内容如下

   package main
   
   import (
      "net/http"
   
      ginSwagger "github.com/swaggo/gin-swagger"
      "github.com/swaggo/gin-swagger/swaggerFiles"
   
      "github.com/gin-gonic/gin"
   )
   
   func setupRouter() *gin.Engine {
      r := gin.Default()
   
      // Ping test
      r.GET("/ping", ping)
   
      //为了可以在浏览器里访问文档界面
      //http://127.0.0.1:8080/swagger/index.html
      r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
      return r
   }
   
   // @Summary 接口探活
   // @Produce  json
   // @Param lang query string false "en"
   // @Success 200 {string} string "ok"
   // @Router /ping [get]
   func ping(c *gin.Context) {
      c.String(http.StatusOK, "ok")
   }
   
   func main() {
      r := setupRouter()
      // Listen and Server in 0.0.0.0:8080
      r.Run(":8080")
   }

   这个代码里有两部分需要重点关注

   • r.GET(“/swagger/*any”, ginSwagger.WrapHandler(swaggerFiles.Handler))：为了可以从浏览器访问生成的文档信息
   • 函数func ping(c *gin.Context) {}上方的注释，这些注释将会自动生成到接口文档中

   此时项目目录为：

   

4. 在项目根目录执行swag init，会生成docs文件夹，里面含有接口文档信息，此时项目目录为：

   swagger.yaml和swagger.json里面会包含接口文档信息

5. import中引入docs，否则执行http://127.0.0.1:8080/swagger/index.html时，看不到接口文档信息

6. 执行go run main.go，然后执行http://127.0.0.1:8080/swagger/index.html，便可看到接口文档信息。也可以使用try it out, 查看该接口返回情况

7. 具体代码可进入github查看：https://github.com/shidawuhen/asap/tree/feature_pzq_swagger

参考资料

1. https://www.jianshu.com/p/4fdac2a10c79 Swagger详细了解一下
2. https://www.jianshu.com/p/dbca3911419e golang restful 框架之 go-swagger
3. https://blog.csdn.net/raogeeg/article/details/86743953 简述 Gin 框架如何集成swagger
4. https://www.cnblogs.com/jehorn/p/9809751.html Golang Gin 项目使用 Swagger
5. https://github.com/go-swagger/go-swagger 源码
6. https://goswagger.io/ 官方文档
7. https://blog.csdn.net/qq_21794823/article/details/78194186 swagger注解说明