使用 swagger 為 Gin 項目生成接口文檔

swagger介紹

Swagger本質(zhì)上是一種用于描述使用JSON表示的RESTful API的接口描述語言。Swagger與一組開源軟件工具一起使用，以設(shè)計、構(gòu)建、記錄和使用RESTful Web服務(wù)。Swagger包括自動文檔，代碼生成和測試用例生成。

在前后端分離的項目開發(fā)過程中，如果后端同學(xué)能夠提供一份清晰明了的接口文檔，那么就能極大地提高大家的溝通效率和開發(fā)效率。可是編寫接口文檔歷來都是令人頭痛的，而且后續(xù)接口文檔的維護也十分耗費精力。

最好是有一種方案能夠既滿足我們輸出文檔的需要又能隨代碼的變更自動更新，而Swagger正是那種能幫我們解決接口文檔問題的工具。

這里以gin框架為例，使用gin-swagger庫以使用Swagger 2.0自動生成RESTful API文檔。

gin-swagger實戰(zhàn)

想要使用gin-swagger為你的代碼自動生成接口文檔，一般需要下面三個步驟：

1. 按照swagger要求給接口代碼添加聲明式注釋，具體參照聲明式注釋格式。
2. 使用swag工具掃描代碼自動生成API接口文檔數(shù)據(jù)
3. 使用gin-swagger渲染在線接口文檔頁面

第一步：添加注釋

在程序入口main函數(shù)上以注釋的方式寫下項目相關(guān)介紹信息。

package?main

//?@title?這里寫標(biāo)題
//?@version?1.0
//?@description?這里寫描述信息
//?@termsOfService?http://swagger.io/terms/

//[email protected]?這里寫聯(lián)系人信息
//[email protected]?http://www.swagger.io/support
//[email protected][email protected]

//[email protected]?Apache?2.0
//[email protected]?http://www.apache.org/licenses/LICENSE-2.0.html

//?@host?這里寫接口服務(wù)的host
//?@BasePath?這里寫base?path
func?main()?{
?r?:=?gin.New()

?//?liwenzhou.com?...

?r.Run()
}

在你代碼中處理請求的接口函數(shù)（通常位于controller層）按如下方式寫上注釋：

//?GetPostListHandler2?升級版帖子列表接口
//?@Summary?升級版帖子列表接口
//?@Description?可按社區(qū)按時間或分數(shù)排序查詢帖子列表接口
//?@Tags?帖子相關(guān)接口
//?@Accept?application/json
//?@Produce?application/json
//?@Param?Authorization?header?string?false?"Bearer?用戶令牌"
//?@Param?object?query?models.ParamPostList?false?"查詢參數(shù)"
//?@Security?ApiKeyAuth
//?@Success?200?{object}?_ResponsePostList
//?@Router?/posts2?[get]
func?GetPostListHandler2(c?*gin.Context)?{
?// GET請求參數(shù)(query string)：/api/v1/posts2?page=1&size=10&order=time
?//?初始化結(jié)構(gòu)體時指定初始參數(shù)
?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)
?//?獲取數(shù)據(jù)
?if?err?!=?nil?{
??zap.L().Error("logic.GetPostList()?failed",?zap.Error(err))
??ResponseError(c,?CodeServerBusy)
??return
?}
?ResponseSuccess(c,?data)
?//?返回響應(yīng)
}

上面注釋中參數(shù)類型使用了object，models.ParamPostList具體定義如下：

//?bluebell/models/params.go

//?ParamPostList?獲取帖子列表query?string參數(shù)
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"`??????//?每頁數(shù)據(jù)量
?Order???????string?`json:"order"?form:"order"?example:"score"`?//?排序依據(jù)
}

響應(yīng)數(shù)據(jù)類型也使用的object，我個人習(xí)慣在controller層專門定義一個docs_models.go文件來存儲文檔中使用的響應(yīng)數(shù)據(jù)model。

//?bluebell/controller/docs_models.go

//?_ResponsePostList?帖子列表接口響應(yīng)數(shù)據(jù)
type?_ResponsePostList?struct?{
?Code????ResCode?????????????????`json:"code"`????//?業(yè)務(wù)響應(yīng)狀態(tài)碼
?Message?string??????????????????`json:"message"`?//?提示信息
?Data????[]*models.ApiPostDetail?`json:"data"`????//?數(shù)據(jù)
}

第二步：生成接口文檔數(shù)據(jù)

編寫完注釋后，使用以下命令安裝swag工具：

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

在項目根目錄執(zhí)行以下命令，使用swag工具生成接口文檔數(shù)據(jù)。

swag?init

執(zhí)行完上述命令后，如果你寫的注釋格式?jīng)]問題，此時你的項目根目錄下會多出一個docs文件夾。

./docs
├──?docs.go
├──?swagger.json
└──?swagger.yaml

第三步：引入gin-swagger渲染文檔數(shù)據(jù)

然后在項目代碼中注冊路由的地方按如下方式引入gin-swagger相關(guān)內(nèi)容：

import?(
?//?liwenzhou.com?...

?_?"bluebell/docs"??//?千萬不要忘了導(dǎo)入把你上一步生成的docs

?gs?"github.com/swaggo/gin-swagger"
?"github.com/swaggo/gin-swagger/swaggerFiles"

?"github.com/gin-gonic/gin"
)

注冊swagger api相關(guān)路由

r.GET("/swagger/*any",?gs.WrapHandler(swaggerFiles.Handler))

把你的項目程序運行起來，打開瀏覽器訪問http://localhost:8080/swagger/index.html就能看到Swagger 2.0 Api文檔了。

gin-swagger同時還提供了DisablingWrapHandler函數(shù)，方便我們通過設(shè)置某些環(huán)境變量來禁用Swagger。例如：

r.GET("/swagger/*any",?gs.DisablingWrapHandler(swaggerFiles.Handler,?"NAME_OF_ENV_VARIABLE"))

此時如果將環(huán)境變量NAME_OF_ENV_VARIABLE設(shè)置為任意值，則/swagger/*any將返回404響應(yīng)，就像未指定路由時一樣。

推薦閱讀

• 煎魚 Go Gin 系列八：為它加上Swagger