golang組件swagger生成接口文檔實(shí)踐示例
swagger介紹
Swagger本質(zhì)上是一種用于描述使用JSON表示的RESTful API的接口描述語(yǔ)言。Swagger與一組開(kāi)源軟件工具一起使用，以設(shè)計(jì)、構(gòu)建、記錄和使用RESTful Web服務(wù)。Swagger包括自動(dòng)文檔，代碼生成和測(cè)試用例生成。
在前后端分離的項(xiàng)目開(kāi)發(fā)過(guò)程中，如果后端同學(xué)能夠提供一份清晰明了的接口文檔，那么就能極大地提高大家的溝通效率和開(kāi)發(fā)效率?？墒蔷帉?xiě)接口文檔歷來(lái)都是令人頭痛的，而且后續(xù)接口文檔的維護(hù)也十分耗費(fèi)精力。
最好是有一種方案能夠既滿足我們輸出文檔的需要又能隨代碼的變更自動(dòng)更新，而Swagger正是那種能幫我們解決接口文檔問(wèn)題的工具。
這里以gin框架為例，使用gin-swagger庫(kù)以使用Swagger 2.0自動(dòng)生成RESTful API文檔。
gin-swagger實(shí)戰(zhàn)
想要使用gin-swagger為你的代碼自動(dòng)生成接口文檔，一般需要下面三個(gè)步驟：
- 按照swagger要求給接口代碼添加聲明式注釋?zhuān)唧w參照聲明式注釋格式。
- 使用swag工具掃描代碼自動(dòng)生成API接口文檔數(shù)據(jù)
- 使用gin-swagger渲染在線接口文檔頁(yè)面
第一步：添加注釋
在程序入口main函數(shù)上以注釋的方式寫(xiě)下項(xiàng)目相關(guān)介紹信息。
package main
// @title 這里寫(xiě)標(biāo)題
// @version 1.0
// @description 這里寫(xiě)描述信息
// @termsOfService http://swagger.io/terms/
// @contact.name 這里寫(xiě)聯(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 這里寫(xiě)接口服務(wù)的host
// @BasePath 這里寫(xiě)base path
func main() {
r := gin.New()
// liwenzhou.com ...
r.Run()
}
在你代碼中處理請(qǐng)求的接口函數(shù)（通常位于controller層）按如下方式寫(xiě)上注釋?zhuān)?/p>
// 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ù)類(lèi)型使用了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"` // 頁(yè)碼
Size int64 `json:"size" form:"size" example:"10"` // 每頁(yè)數(shù)據(jù)量
Order string `json:"order" form:"order" example:"score"` // 排序依據(jù)
}
響應(yīng)數(shù)據(jù)類(lèi)型也使用的object，我個(gè)人習(xí)慣在controller層專(zhuān)門(mén)定義一個(gè)docs_models.go文件來(lái)存儲(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ù)
編寫(xiě)完注釋后，使用以下命令安裝swag工具：
go get -u github.com/swaggo/swag/cmd/swag
在項(xiàng)目根目錄執(zhí)行以下命令，使用swag工具生成接口文檔數(shù)據(jù)。
swag init
執(zhí)行完上述命令后，如果你寫(xiě)的注釋格式?jīng)]問(wèn)題，此時(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" // 千萬(wàn)不要忘了導(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)行起來(lái)，打開(kāi)瀏覽器訪問(wèn)http://localhost:8080/swagger/index.html就能看到Swagger 2.0 Api文檔了。
gin-swagger同時(shí)還提供了DisablingWrapHandler函數(shù)，方便我們通過(guò)設(shè)置某些環(huán)境變量來(lái)禁用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í)一樣。
以上就是golang組件swagger生成接口文檔實(shí)踐示例的詳細(xì)內(nèi)容，更多關(guān)于golang組件swagger生成接口文檔實(shí)的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！
相關(guān)文章
GO語(yǔ)言對(duì)數(shù)組切片去重的實(shí)現(xiàn)
本文主要介紹了GO語(yǔ)言對(duì)數(shù)組切片去重的實(shí)現(xiàn)，主要介紹了幾種方法，文中通過(guò)示例代碼介紹的非常詳細(xì)，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2022-04-04
Go語(yǔ)言sync包與鎖實(shí)現(xiàn)限制線程對(duì)變量的訪問(wèn)
本文主要介紹了Go語(yǔ)言sync包與鎖實(shí)現(xiàn)限制線程對(duì)變量的訪問(wèn)，文中通過(guò)示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，需要的朋友們下面隨著小編來(lái)一起學(xué)習(xí)學(xué)習(xí)吧2023-04-04
golang的database.sql包和事務(wù)處理操作步驟
事務(wù)是數(shù)據(jù)庫(kù)操作中的一個(gè)邏輯單元,由一系列的數(shù)據(jù)庫(kù)操作組成,這一系列操作要么全部執(zhí)行并且提交,要么全部回滾,確保數(shù)據(jù)的一致性和完整性,這篇文章主要介紹了golang的database.sql包和事務(wù)處理操作步驟,需要的朋友可以參考下2025-04-04
這篇文章主要詳細(xì)介紹了Go 1.22 for循環(huán)的兩處重要更新,Go 1.22 版本于 2024 年 2 月 6 日發(fā)布,引入了幾個(gè)重要的特性和改進(jìn),在語(yǔ)言層面上,這個(gè)版本對(duì) for 循環(huán)進(jìn)行了兩處更新,本文將會(huì)對(duì) for 循環(huán)的兩個(gè)更新進(jìn)行介紹,需要的朋友可以參考下2024-02-02
golang 實(shí)用庫(kù)gotable的具體使用
使用gotable框架以實(shí)現(xiàn)在CLI命令行界面中打印表格。本文就介紹一下golang 實(shí)用庫(kù)gotable的使用，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2021-07-07
Go語(yǔ)言學(xué)習(xí)之結(jié)構(gòu)體和方法使用詳解
這篇文章主要為大家詳細(xì)介紹了Go語(yǔ)言中結(jié)構(gòu)體和方法的使用，文中的示例代碼講解詳細(xì)，對(duì)我們學(xué)習(xí)Go語(yǔ)言有一定的幫助，需要的可以參考一下2022-04-04
VSCode是我們開(kāi)發(fā)go程序的常用工具,但是安裝VSCode成功后,創(chuàng)建一個(gè).go文件居然提示錯(cuò)誤了,所以下面下面這篇文章主要給大家介紹了如何通過(guò)一招完美解決vscode安裝go插件失敗問(wèn)題的相關(guān)資料,需要的朋友可以參考下2022-07-07
這篇文章主要介紹了Go開(kāi)發(fā)神器Air熱加載使用實(shí)例探究,有需要的朋友可以借鑒參考下,希望能夠有所幫助,祝大家多多進(jìn)步,早日升職加薪2024-01-01
golang字符串拼接實(shí)現(xiàn)方式和區(qū)別對(duì)比
本文介紹了Go語(yǔ)言中字符串拼接的多種方法及其優(yōu)缺點(diǎn),推薦使用strings.Builder進(jìn)行頻繁拼接以優(yōu)化內(nèi)存分配和性能,同時(shí),還討論了通過(guò)sync.Pool優(yōu)化高頻創(chuàng)建的對(duì)象,以減少垃圾回收壓力,感興趣的朋友一起看看吧2025-02-02
Go緩沖channel和非緩沖channel的區(qū)別說(shuō)明
這篇文章主要介紹了Go緩沖channel和非緩沖channel的區(qū)別說(shuō)明，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。一起跟隨小編過(guò)來(lái)看看吧2021-04-04