Gin-Swagger 使用篇

Swagger相信Web开发都非常熟悉了，当我们使用Golang的web开发框架Gin的时候，如何使用Swagger呢

这个时候就可以使用gin-swagger了，先来看看gin-swagger官方描述：

gin middleware to automatically generate RESTFUL API documentation with Swagger 2.0.

git地址：https://github.com/swaggo/gin-swagger/tree/master/

1、首先得下载Swag for Go：

?

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

然后还需下载两个依赖包：

?

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

2、在main.go文件中将Swagger的总体注释写进去：

?

1 2 3 4 5 6 7 8 9

// @title IvanApi Swagger 标题 // @version 1.0 版本 // @description IvanApi Service 描述 // @BasePath /api/v1  基础路径 // @query.collection.format multi func main() {     r := Router.Router()     r.Run(":8081") }

 这样就把基础的swagger信息写好了，当然还有其他可用参数，详情请看官方文档。

3、注册Swagger api相关路由

?

1 2	docs.SwaggerInfo.BasePath = "/api/v1" r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))

Full Code

?

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

import (     "IvanApi/Apis"     docs "IvanApi/docs"     "github.com/gin-gonic/gin"     swaggerfiles "github.com/swaggo/files"     ginSwagger "github.com/swaggo/gin-swagger" )   func Router()  *gin.Engine{     r := gin.New()     docs.SwaggerInfo.BasePath = "/api/v1"     r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))     v1 := r.Group("/api/v1")     {         eg := v1.Group("/ops")         {             eg.GET("/getbroadcast",Apis.GetBroadCastList)         }     }       return r }

 4、完善Api函数注释

Get请求

?

1 2 3 4 5 6 7 8 9 10 11 12

// @Summary 摘要 比如获取用户列表 // @Schemes // @Description 这里写描述 get users // @Tags ops 标签 比如同类功能使用同一个标签 // @Param Id query int true "Id"     参数 ：@Param 参数名 位置（query 或者 path或者 body） 类型 是否必需 注释 // @Accept json // @Produce json // @Success 200 {object} Model.PageResult GetUser 返回结果 200 类型（object就是结构体） 类型 注释 // @Router /user [get]  func GetUserList(g *gin.Context)  {   g.JSON(http.StatusOK, nil)  }

Put请求

?

1 2 3 4 5 6 7 8 9 10 11

// @Summary 修改 // @Schemes // @Description update // @Tags ops // @Param userinput body Model.UserUpdateInput true "入参" // @Accept json // @Produce json // @Success 200 {object} Model.ResponseResult UpdateUser // @Router /user [put] func UpdateUser(g *gin.Context) { }

　　

5、完善模型注释

?

1 2 3 4 5 6 7

// 响应数据 type PageResult struct{     Total int `json:"total"` // 总条数     PageSize int `json:"pageSize"` // 页码     PageIndex int `json:"pageIndex"` // 页签     Result interface{} `json:"result"` // 结果 }

 模型这里直接后面加注释就可以了，swagger会自动生成注释

6、生成swagger文件

在终端输入：

?

1

swag init

 这里要有注意的点，就是每一次修改swagger注释还有其他参数的时候需要重新生成swagger文件才会生效