golang組件swagger生成接口文檔的方法

這篇文章主要介紹“golang組件swagger生成接口文檔的方法”的相關(guān)知識(shí)，小編通過實(shí)際案例向大家展示操作過程，操作方法簡(jiǎn)單快捷，實(shí)用性強(qiáng)，希望這篇“golang組件swagger生成接口文檔的方法”文章能幫助大家解決問題。

swagger介紹

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

在前后端分離的項(xiàng)目開發(fā)過程中，如果后端同學(xué)能夠提供一份清晰明了的接口文檔，那么就能極大地提高大家的溝通效率和開發(fā)效率?？墒蔷帉懡涌谖臋n歷來都是令人頭痛的，而且后續(xù)接口文檔的維護(hù)也十分耗費(fèi)精力。

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

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

gin-swagger實(shí)戰(zhàn)

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

• 按照swagger要求給接口代碼添加聲明式注釋，具體參照聲明式注釋格式。

• 使用swag工具掃描代碼自動(dòng)生成API接口文檔數(shù)據(jù)

• 使用gin-swagger渲染在線接口文檔頁面

第一步：添加注釋

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

package main
// @title 這里寫標(biāo)題
// @version 1.0
// @description 這里寫描述信息
// @termsOfService http://swagger.io/terms/
// @contact.name 這里寫聯(lián)系人信息
// @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 這里寫接口服務(wù)的host
// @BasePath 這里寫base path
func main() {
	r := gin.New()
	// liwenzhou.com ...
	r.Run()
}

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

// GetPostListHandler2 升級(jí)版帖子列表接口
// @Summary 升級(jí)版帖子列表接口
// @Description 可按社區(qū)按時(shí)間或分?jǐn)?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請(qǐng)求參數(shù)(query string)：/api/v1/posts2?page=1&size=10&order=time
	// 初始化結(jié)構(gòu)體時(shí)指定初始參數(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，我個(gè)人習(xí)慣在controller層專門定義一個(gè)docs_models.go文件來存儲(chǔ)文檔中使用的響應(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

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

swag init

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

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

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

然后在項(xiàng)目代碼中注冊(cè)路由的地方按如下方式引入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"
)

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

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

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

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

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

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

關(guān)于“golang組件swagger生成接口文檔的方法”的內(nèi)容就介紹到這里了，感謝大家的閱讀。如果想了解更多行業(yè)相關(guān)的知識(shí)，可以關(guān)注億速云行業(yè)資訊頻道，小編每天都會(huì)為大家更新不同的知識(shí)點(diǎn)。