使用swagger生成API文件

有時候乙份清晰明了的介面文件能夠極大地提高前後端雙方的溝通效率和開發效率。本文將介紹如何使用swagger生成介面文件。

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()  _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

然後在專案**中註冊路由的地方按如下方式引入gin-swagger

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同時還提供了disablingwraphandler函式，方便我們通過設定某些環境變數來禁用swagger。例如：

r.get("/swagger/*any", gs.disablingwraphandler(swaggerfiles.handler, "name_of_env_variable"))

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

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

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

使用Swagger建立Api

1.首先建立乙個web專案,選擇mvc模板此時會發現 config.maphttpattributeroutes 飄紅報錯.此時需在引用 microsoft.aspnet.webapi.webhost 包.然後就不報錯了.5.在global.asax呼叫剛才新增的類的register方法.6.右鍵...

05 配置Swagger2生成API介面文件

前後端分離開發模式中，api文件是最好的溝通方式。swagger 是乙個規範和完整的框架，用於生成描述呼叫和視覺化 restful 風格的 web 服務。及時性介面變更後，能夠及時準確地通知相關前後端開發人員規範性並且保證介面的規範性，如介面的位址，請求方式，引數及響應格式和錯誤資訊一致...

使用swagger生成API文件

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

使用Swagger建立Api

05 配置Swagger2生成API介面文件

相關推薦