使用swagger生成API文檔

有時候一份清晰明了的接口文檔能夠極大地提高前后端雙方的溝通效率和開發效率。本文將介紹如何使用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 [e-mail]


// @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同時還提供了DisablingWrapHandler函數，方便我們通過設置某些環境變量來禁用Swagger。例如：

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

此時如果將環境變量NAME_OF_ENV_VARIABLE設置為任意值，則/swagger/*any將返回404響應，就像未指定路由時一樣