Go語言使用swagger生成接口文檔

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同時還提供了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開發實戰視頻課程，歡迎點擊博客右上角圖片瞭解。