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：

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

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

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

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

// @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相关路由

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

Full Code

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请求

　　// @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请求

// @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、完善模型注释

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

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

6、生成swagger文件

在终端输入：

swag init

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