swagger介紹
Swagger本質上是一種用于描述使用JSON表示的RESTful API的介面描述語言，Swagger與一組開源軟體工具一起使用，以設計、構建、記錄和使用RESTful Web服務，Swagger包括自動檔案，代碼生成和測驗用例生成，
在前后端分離的專案開發程序中，如果后端同學能夠提供一份清晰明了的介面檔案，那么就能極大地提高大家的溝通效率和開發效率，可是撰寫介面檔案歷來都是令人頭痛的，而且后續介面檔案的維護也十分耗費精力，
最好是有一種方案能夠既滿足我們輸出檔案的需要又能隨代碼的變更自動更新，而Swagger正是那種能幫我們解決介面檔案問題的工具，
這里以gin框架為例，使用gin-swagger庫以使用Swagger 2.0自動生成RESTful API檔案，
gin-swagger實戰
想要使用gin-swagger為你的代碼自動生成介面檔案，一般需要下面三個步驟：
- 按照swagger要求給介面代碼添加宣告式注釋，具體參照宣告式注釋格式，
- 使用swag工具掃描代碼自動生成API介面檔案資料
- 使用gin-swagger渲染在線介面檔案頁面
第一步：添加注釋
在程式入口main函式上以注釋的方式寫下專案相關介紹資訊，
package main
// @title 這里寫標題
// @version 1.0
// @description 這里寫描述資訊
// @termsOfService http://swagger.io/terms/
// @contact.name 這里寫聯系人資訊
// @contact.url http://www.swagger.io/support
// @contact.email [email protected]
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host 這里寫介面服務的host
// @BasePath 這里寫base path
func main() {
r := gin.New()
// liwenzhou.com ...
r.Run()
}
在你代碼中處理請求的介面函式（通常位于controller層）按如下方式寫上注釋：
// GetPostListHandler2 升級版帖子串列介面
// @Summary 升級版帖子串列介面
// @Description 可按社區按時間或分數排序查詢帖子串列介面
// @Tags 帖子相關介面
// @Accept application/json
// @Produce application/json
// @Param Authorization header string false "Bearer 用戶令牌"
// @Param object query models.ParamPostList false "查詢引數"
// @Security ApiKeyAuth
// @Success 200 {object} _ResponsePostList
// @Router /posts2 [get]
func GetPostListHandler2(c *gin.Context) {
// GET請求引數(query string)：/api/v1/posts2?page=1&size=10&order=time
// 初始化結構體時指定初始引數
p := &models.ParamPostList{
Page: 1,
Size: 10,
Order: models.OrderTime,
}
if err := c.ShouldBindQuery(p); err != nil {
zap.L().Error("GetPostListHandler2 with invalid params", zap.Error(err))
ResponseError(c, CodeInvalidParam)
return
}
data, err := logic.GetPostListNew(p)
// 獲取資料
if err != nil {
zap.L().Error("logic.GetPostList() failed", zap.Error(err))
ResponseError(c, CodeServerBusy)
return
}
ResponseSuccess(c, data)
// 回傳回應
}
上面注釋中引數型別使用了object，models.ParamPostList具體定義如下：
// bluebell/models/params.go
// ParamPostList 獲取帖子串列query string引數
type ParamPostList struct {
CommunityID int64 `json:"community_id" form:"community_id"` // 可以為空
Page int64 `json:"page" form:"page" example:"1"` // 頁碼
Size int64 `json:"size" form:"size" example:"10"` // 每頁資料量
Order string `json:"order" form:"order" example:"score"` // 排序依據
}
回應資料型別也使用的object，我個人習慣在controller層專門定義一個docs_models.go檔案來存盤檔案中使用的回應資料model，
// bluebell/controller/docs_models.go
// _ResponsePostList 帖子串列介面回應資料
type _ResponsePostList struct {
Code ResCode `json:"code"` // 業務回應狀態碼
Message string `json:"message"` // 提示資訊
Data []*models.ApiPostDetail `json:"data"` // 資料
}
第二步：生成介面檔案資料
撰寫完注釋后，使用以下命令安裝swag工具：
go get -u github.com/swaggo/swag/cmd/swag
在專案根目錄執行以下命令，使用swag工具生成介面檔案資料，
swag init
執行完上述命令后，如果你寫的注釋格式沒問題，此時你的專案根目錄下會多出一個docs檔案夾，
./docs
├── docs.go
├── swagger.json
└── swagger.yaml
第三步：引入gin-swagger渲染檔案資料
然后在專案代碼中注冊路由的地方按如下方式引入gin-swagger相關內容：
import (
// liwenzhou.com ...
_ "bluebell/docs" // 千萬不要忘了匯入把你上一步生成的docs
gs "github.com/swaggo/gin-swagger"
"github.com/swaggo/gin-swagger/swaggerFiles"
"github.com/gin-gonic/gin"
)
注冊swagger api相關路由
r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))
把你的專案程式運行起來，打開瀏覽器訪問http://localhost:8080/swagger/index.html就能看到Swagger 2.0 Api檔案了，
gin_swagger檔案
gin-swagger同時還提供了DisablingWrapHandler函式，方便我們通過設定某些環境變數來禁用Swagger，例如：
r.GET("/swagger/*any", gs.DisablingWrapHandler(swaggerFiles.Handler, "NAME_OF_ENV_VARIABLE"))
此時如果將環境變數NAME_OF_ENV_VARIABLE設定為任意值，則/swagger/*any將回傳404回應，就像未指定路由時一樣，
本文首發于我的個人博客：liwenzhou.com
更多更詳細的go web開發實戰視頻課程，歡迎點擊博客右上角圖片了解，
轉載請註明出處，本文鏈接：https://www.uj5u.com/houduan/338.html
標籤：Go