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

本文首發於我的個人部落格：liwenzhou.com，更多更詳細的go語言專案實戰內容就在liwenzhou.com。

swagger本質上是一種用於描述使用json表示的restful api的介面描述語言。swagger與一組開源軟體工具一起使用，以設計、構建、記錄和使用restful web服務。swagger包括自動文件，**生成和測試用例生成。

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

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

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

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

按照swagger要求給介面**新增宣告式注釋，具體參照宣告式注釋格式。

使用swag工具掃瞄**自動生成api介面文件資料

在程式入口main函式上以注釋的方式寫下專案相關介紹資訊。

package main
// @title 這裡寫標題
// @version 1.0
// @description 這裡寫描述資訊
// @termsofservice 
// @contact.name 這裡寫聯絡人資訊
// @contact.url 
// @contact.email [email protected]
// @license.name apache 2.0
// @license.url 
// @host 這裡寫介面服務的host
// @basepath 這裡寫base path
func
main
()

在你**中處理請求的介面函式（通常位於controller層）按如下方式寫上注釋：

// getpostlisthandler2 公升級版帖子列表介面
// @summary 公升級版帖子列表介面
// @description 可按社群按時間或分數排序查詢帖子列表介面
// @tags 帖子相關介面
// @param authorization header string false "bearer 使用者令牌"
// @param object query models.parampostlist false "查詢引數"
// @security apikeyauth
// @success 200  _responsepostlist
// @router /posts2 [get]
func
getpostlisthandler2
(c *gin.context)
if err := c.shouldbindquery(p); err != nil 
data, err := logic.getpostlistnew(p)
// 獲取資料
if err != nil 
responsesuccess(c, data)
// 返回響應
}

上面注釋中引數型別使用了object，models.parampostlist具體定義如下：

// bluebell/models/params.go
// parampostlist 獲取帖子列表query string引數
type parampostlist struct

響應資料型別也使用的object，我個人習慣在controller層專門定義乙個docs_models.go檔案來儲存文件中使用的響應資料model。

// bluebell/controller/docs_models.go
// _responsepostlist 帖子列表介面響應資料
type _responsepostlist struct

編寫完注釋後，使用以下命令安裝swag工具：

go get -u github.com/swaggo/swag/cmd/swag

在專案根目錄執行以下命令，使用swag工具生成介面文件資料。

swag init

執行完上述命令後，如果你寫的注釋格式沒問題，此時你的專案根目錄下會多出乙個docs資料夾。

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

import (
// liwenzhou.com ...
_ "bluebell/docs"
// 千萬不要忘了匯入把你上一步生成的docs
)

註冊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語言專案實戰內容就在liwenzhou.com。

使用swagger生成restful風格的介面文件

專案中如何配置swagger？下方鏈結 springboot整合swagger 匯入依賴 org.projectlombokgroupid lombokartifactid 1.16.18version providedscope dependency io.springfoxgroupid spr...

使用swagger生成API文件

有時候乙份清晰明了的介面文件能夠極大地提高前後端雙方的溝通效率和開發效率。本文將介紹如何使用swagger生成介面文件。swagger本質上是一種用於描述使用json表示的restful api的介面描述語言。swagger與一組開源軟體工具一起使用，以設計構建記錄和使用restful web服...

go實踐之swagger自動生成api文件

作為乙個後端開發，給前端提供api介面是必須的。手動去寫文件不是乙個程式設計師的風格。swagger就是乙個很好的api文件生成該工具，go當然也支援了。下面看看怎麼使用這個工具。安裝gin swagger，用來整合到我們前一篇文章go實踐之apiserver搭建實現的apiserver當中去。在r...

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

使用swagger生成restful風格的介面文件

使用swagger生成API文件

go實踐之swagger自動生成api文件

相關推薦