Go語言使用swagger生成介面文件

Q1mi發表於2020-09-07
GoSwagger

swagger介紹

Swagger本質上是一種用於描述使用JSON表示的RESTful API的介面描述語言。Swagger與一組開源軟體工具一起使用，以設計、構建、記錄和使用RESTful Web服務。Swagger包括自動文件，程式碼生成和測試用例生成。

在前後端分離的專案開發過程中，如果後端同學能夠提供一份清晰明瞭的介面文件，那麼就能極大地提高大家的溝通效率和開發效率。可是編寫介面文件歷來都是令人頭痛的，而且後續介面文件的維護也十分耗費精力。

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

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

gin-swagger實戰

想要使用gin-swagger為你的程式碼自動生成介面文件，一般需要下面三個步驟：

  1. 按照swagger要求給介面程式碼新增宣告式註釋，具體參照宣告式註釋格式。
  2. 使用swag工具掃描程式碼自動生成API介面文件資料
  3. 使用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 support@swagger.io

// @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文件

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開發實戰視訊課程，歡迎點選部落格右上角圖片瞭解。

相關文章