中年大叔學編程-Gin-Swagger生成API接口文檔

最近簡單的學習了一下Golang，並且用Gin開發了兩個小應用，一個短域名生成，一個微信小程序。感受到了Golang的代碼簡潔、部署簡單、內存佔用少、零停機平滑重啟等優勢。在開發小程序的時候，需要生成接口文檔，這裡需要用到Gin-Swagger了，所以簡單的就來整理一下。

這裡我用的環境是：

• go version go1.14.6 windows/amd64
• GoLand 2020.2.1
• gin v1.6.3
• swag v1.6.7

這裡先用Goland新建一個demo項目吧,在新建的時候，我們最好就要把包的代理地址配置好

這裡我們需要安裝Gin、swag、gin-swagger、files幾個包，可以通過命令的方式

go get -u github.com/gin-gonic/gingo get -u github.com/swaggo/swag/cmd/swaggo get -u github.com/swaggo/gin-swaggergo get -u github.com/swaggo/files

但是在Goland中，會自動獲取複製的連接，然後提醒安裝，直接點擊相應的按鈕即可，非常方便。 這裡我們新建一個main.go文件，加入如下代碼

import ( _ &34; &34; swaggerFiles &34; ginSwagger &34;)func main() { r := gin.New() // use ginSwagger middleware to r.GET(&34;, ginSwagger.WrapHandler(swaggerFiles.Handler)) r.Run()}

然後進入Terminal中執行swag init

現在，運行項目(默認8080埠)並訪問http://localhost:8080/swagger/index.html

因為現在還沒有開發相應的接口，所以什麼信息都沒有，在開始之前，我們需要先了解一下gin-swagger的註解

• @Tags 接口分組，相當於歸類
• @Summary 接口的簡要描述
• @Description 接口的詳細描述
• @Id 全局標識符
• @Version 接口版本號
• @Accept 發起請求的數據類型
• @Produce 接口返回的數據類型
• @Param 請求參數描述
• @Success 請求成功後返回信息
• @Failure 請求失敗後返回信息
• @Router 請求的路由路徑和請求方式。
• @contact.name 接口聯繫人
• @contact.url 聯繫人網址
• @contact.email 聯繫人郵箱

上面就是一些較為基礎的參數說明，當然還有一些更加複雜的，比如@security,@in等，這些以後再說吧，我們就可以在相應的Controller方法上加註解了

// @Tags Demo// @Id 1// @Summary 接口Demo// @Description 接口詳細描述信息// @Produce json// @Param id path int true &34;// @Success 200 {string} string// @Failure 400 {string} string// @Router /api/v1/demo/{id} [get]// @contact.name 中年大叔學編程// @contact.email [e-mail] Demo(c *gin.Context) { c.JSON(200,&34;)}

在main方法中註冊路由

r.GET(&34;, controller.Demo)

現在，進入Terminal中再次執行swag init並啟動，這時候就可以看到對應的內容了

我們來執行以下看看效果

這樣一個API接口文檔就有了，而且還方便我們調試。

我只是記錄我的學習過程，由於書讀得少，可能很多地方表述或者是理解得不對，請輕噴並指正。