go swagger生成接口文檔使用教程
前言
這篇文章主要介紹了Go語(yǔ)言使用swagger生成接口文檔的方法,希望能夠?qū)Υ蠹业膶W(xué)習(xí)或工作具有一定的幫助,需要的朋友可以參考下。
在前后端分離的項(xiàng)目開(kāi)發(fā)過(guò)程中,如果后端同學(xué)能夠提供一份清晰明了的接口文檔,那么就能極大地提高大家的溝通效率和開(kāi)發(fā)效率。那如何維護(hù)接口文檔,歷來(lái)都是令人頭痛的,感覺(jué)很浪費(fèi)精力,而且后續(xù)接口文檔的維護(hù)也十分耗費(fèi)精力。在很多年以前,也流行用word等工具寫接口文檔,這里面的問(wèn)題很多,如格式不統(tǒng)一、后端人員消費(fèi)精力大、文檔的時(shí)效性也無(wú)法保障。
針對(duì)這類問(wèn)題,最好是有一種方案能夠既滿足我們輸出文檔的需要又能隨代碼的變更自動(dòng)更新,Swagger正是那種能幫我們解決接口文檔問(wèn)題的工具。
Swagger介紹
Swagger是基于標(biāo)準(zhǔn)的 OpenAPI 規(guī)范進(jìn)行設(shè)計(jì)的,本質(zhì)是一種用于描述使用json表示的Restful Api的接口描述語(yǔ)言,只要照著這套規(guī)范去編寫你的注解或通過(guò)掃描代碼去生成注解,就能生成統(tǒng)一標(biāo)準(zhǔn)的接口文檔和一系列 Swagger 工具。Swagger包括自動(dòng)文檔,代碼生成和測(cè)試用例生成。
1、安裝
go get -u github.com/swaggo/swag/cmd/swag
在macOS中安裝 swag需要執(zhí)行如下命令:
mv $GOPATH/bin/swag /usr/local/go/bin
2、檢測(cè)是否安裝成功
$ swag -v swag version v1.8.4
3、安裝gin-swagger擴(kuò)展
$ go get -u -v github.com/swaggo/gin-swagger $ go get -u -v github.com/swaggo/files $ go get -u -v github.com/alecthomas/template
使用
使用gin-swagger為你的代碼自動(dòng)生成接口文檔,一般需要下面三個(gè)步驟:
- 按照swagger要求給接口代碼添加聲明式注釋。
- 使用swag工具掃描代碼自動(dòng)生成api接口文檔數(shù)據(jù)。
- 使用gin-swagger渲染在線接口文檔頁(yè)面。
1、添加注釋
go-swapper注解規(guī)范說(shuō)明:
注:注解詳情可參見(jiàn)官網(wǎng)文檔Swagger Documentation
注解 | 描述 |
---|---|
@Summary | 摘要 |
@Produce | API 可以產(chǎn)生的 MIME 類型的列表,MIME 類型你可以簡(jiǎn)單的理解為響應(yīng)類型,例如:json、xml、html 等等 |
@Param | 參數(shù)格式,從左到右分別為:參數(shù)名、入?yún)㈩愋汀?shù)據(jù)類型、是否必填、注釋 |
@Success | 響應(yīng)成功,從左到右分別為:狀態(tài)碼、參數(shù)類型、數(shù)據(jù)類型、注釋 |
@Failure | 響應(yīng)失敗,從左到右分別為:狀態(tài)碼、參數(shù)類型、數(shù)據(jù)類型、注釋 |
@Router | 路由,從左到右分別為:路由地址,HTTP 方法 |
示例demo:
package main import ( "github.com/gin-gonic/gin" "github.com/swaggo/files" ginSwagger "github.com/swaggo/gin-swagger" _ "github/mwqnice/swag/docs" // 千萬(wàn)不要忘了導(dǎo)入把你上一步生成的docs ) type Article struct{ ID uint32 `gorm:"primary_key" json:"id"` CreatedBy string `json:"created_by"` ModifiedBy string `json:"modified_by"` CreatedOn uint32 `json:"created_on"` ModifiedOn uint32 `json:"modified_on"` DeletedOn uint32 `json:"deleted_on"` IsDel uint8 `json:"is_del"` Title string `json:"title"` Desc string `json:"desc"` Content string `json:"content"` CoverImageUrl string `json:"cover_image_url"` State uint8 `json:"state"` } func NewArticle() Article { return Article{} } func main() { r := gin.Default() r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) r.Run(":8088") } // @Summary 獲取單個(gè)文章 // @Produce json // @Param id path int true "文章ID" // @Success 200 {object} Article "成功" // @Failure 400 {object} string "請(qǐng)求錯(cuò)誤" // @Failure 500 {object} string "內(nèi)部錯(cuò)誤" // @Router /api/v1/articles/{id} [get] func (a Article) Get(c *gin.Context) { } // @Summary 獲取多個(gè)文章 // @Produce json // @Param name query string false "文章名稱" // @Param tag_id query int false "標(biāo)簽ID" // @Param state query int false "狀態(tài)" // @Param page query int false "頁(yè)碼" // @Param page_size query int false "每頁(yè)數(shù)量" // @Success 200 {object} Article "成功" // @Failure 400 {object} string "請(qǐng)求錯(cuò)誤" // @Failure 500 {object} string "內(nèi)部錯(cuò)誤" // @Router /api/v1/articles [get] func (a Article) List(c *gin.Context) { return } // @Summary 創(chuàng)建文章 // @Produce json // @Param tag_id body string true "標(biāo)簽ID" // @Param title body string true "文章標(biāo)題" // @Param desc body string false "文章簡(jiǎn)述" // @Param cover_image_url body string true "封面圖片地址" // @Param content body string true "文章內(nèi)容" // @Param created_by body int true "創(chuàng)建者" // @Param state body int false "狀態(tài)" // @Success 200 {object} Article "成功" // @Failure 400 {object} string "請(qǐng)求錯(cuò)誤" // @Failure 500 {object} string "內(nèi)部錯(cuò)誤" // @Router /api/v1/articles [post] func (a Article) Create(c *gin.Context) { } // @Summary 更新文章 // @Produce json // @Param tag_id body string false "標(biāo)簽ID" // @Param title body string false "文章標(biāo)題" // @Param desc body string false "文章簡(jiǎn)述" // @Param cover_image_url body string false "封面圖片地址" // @Param content body string false "文章內(nèi)容" // @Param modified_by body string true "修改者" // @Success 200 {object} Article "成功" // @Failure 400 {object} string "請(qǐng)求錯(cuò)誤" // @Failure 500 {object} string "內(nèi)部錯(cuò)誤" // @Router /api/v1/articles/{id} [put] func (a Article) Update(c *gin.Context) { return } // @Summary 刪除文章 // @Produce json // @Param id path int true "文章ID" // @Success 200 {string} string "成功" // @Failure 400 {object} string "請(qǐng)求錯(cuò)誤" // @Failure 500 {object} string "內(nèi)部錯(cuò)誤" // @Router /api/v1/articles/{id} [delete] func (a Article) Delete(c *gin.Context) { return }
2、生成接口文檔數(shù)據(jù)
格式化swag注解
$ swag fmt
在項(xiàng)目根目錄執(zhí)行以下命令,使用swag工具生成接口文檔數(shù)據(jù)。
$ swag init
執(zhí)行完上述命令后,如果你寫的注釋格式?jīng)]問(wèn)題,此時(shí)你的項(xiàng)目根目錄下會(huì)多出一個(gè)docs文件夾。
./docs
├── docs.go
├── swagger.json
└── swagger.yaml
3、引入gin-swagger渲染文檔數(shù)據(jù)
然后在項(xiàng)目代碼中注冊(cè)路由的地方按如下方式引入gin-swagger相關(guān)內(nèi)容:
import ( "github.com/gin-gonic/gin" "github.com/swaggo/files" ginSwagger "github.com/swaggo/gin-swagger" _ "github/mwqnice/swag/docs" // 千萬(wàn)不要忘了導(dǎo)入把你上一步生成的docs ) //添加swagger訪問(wèn)路由 r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
啟動(dòng)項(xiàng)目,在瀏覽器中輸入地址:http://127.0.0.1:8088/swagger/index.html
總結(jié)
到此這篇關(guān)于go語(yǔ)言使用swagger生成接口文檔的文章就介紹到這了, 希望可以對(duì)你的開(kāi)發(fā)有一定幫助。
更多關(guān)于go swagger接口文檔的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章!
相關(guān)文章
Go 微服務(wù)開(kāi)發(fā)框架DMicro設(shè)計(jì)思路詳解
這篇文章主要為大家介紹了Go 微服務(wù)開(kāi)發(fā)框架DMicro設(shè)計(jì)思路詳解,有需要的朋友可以借鑒參考下,希望能夠有所幫助,祝大家多多進(jìn)步,早日升職加薪2022-10-10golang語(yǔ)言實(shí)現(xiàn)的文件上傳與文件下載功能示例
這篇文章主要介紹了golang語(yǔ)言實(shí)現(xiàn)的文件上傳與文件下載功能,結(jié)合實(shí)例形式分析了Go語(yǔ)言實(shí)現(xiàn)的文件傳輸相關(guān)操作技巧,需要的朋友可以參考下2020-02-02Go編寫定時(shí)器與定時(shí)任務(wù)詳解(附第三方庫(kù)gocron用法)
當(dāng)需要每天執(zhí)行定時(shí)任務(wù)的時(shí)候就需要定時(shí)器來(lái)處理了,周期任務(wù),倒計(jì)時(shí)任務(wù),定點(diǎn)任務(wù)等,下面這篇文章主要給大家介紹了關(guān)于Go編寫定時(shí)器與定時(shí)任務(wù)的相關(guān)資料,文中通過(guò)實(shí)例代碼介紹的非常詳細(xì),需要的朋友可以參考下2022-07-07K8s部署發(fā)布Golang應(yīng)用程序的實(shí)現(xiàn)方法
本文主要介紹了K8s部署發(fā)布Golang應(yīng)用程序的實(shí)現(xiàn)方法,文中通過(guò)示例代碼介紹的非常詳細(xì),需要的朋友們下面隨著小編來(lái)一起學(xué)習(xí)學(xué)習(xí)吧2021-07-07