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文件才會生效