Gin(十):集成 Swagger

原文首發於 ISALND

你喜歡寫文檔嗎？ 我喜歡。

因此說文檔成了開發心中的一個痛。尤爲是使用 restful 接口，成了必需要寫文檔，否者前端同窗根本不知道你寫了什麼。那麼讓我寫文檔，還不如殺了我呢！！！

接下來介紹一款神器 --- swagger

📜什麼是swagger

Swagger 是一個 API 生成工具，能夠生成文檔。 Swagger 是經過編寫 yaml 和 json 來實現文檔化。而且能夠進行測試等工做。

經過 swagger 能夠方便的生成接口文檔，方便前端進行查看和測試。

🔧安裝 swagger

上面說了一堆 swagger 怎麼樣，說到頭仍是要本身編寫？其實並非的，讓咱們的項目中集成 swagger，之後項目的接口文檔即可以自動生成。

首先要安裝 swagger 。

go get -u github.com/swaggo/swag/cmd/swag
複製代碼

等待安裝完成，在咱們的終端中執行 swag init，目錄爲根目錄，於 main.go 同目錄。

執行完成後，會在根目錄下新建一個 docs 文件夾。

docs
|
|-docs.go
|-swagger.json
|-swagger.yaml
複製代碼

接下來就能夠完善項目了。

將下面兩行放入 initRouter 中的 import 中。

swaggerFiles "github.com/swaggo/files"
ginSwagger "github.com/swaggo/gin-swagger"
複製代碼

選擇 Sync packages of GinHello,此時 IDE 就會自動幫我下載，並添加到 go.mod 中。

若是這裏提示下載失敗，請對 go mod 添加代理。

添加代理 File-Setting-Go-Go Modules(vgo)-Proxy
代理添加 mirrors.aliyun.com/goproxy/ 這是最近阿里創建的 go mod 鏡像。固然你也能夠選擇其餘鏡像代理。

等待包下載完成。

🍔集成 swagger

對 swagger 安裝完成後，咱們就能夠對項目進行集成了。

在 initRouter 中添加路由，這個路由是對 swagger 的訪問地址來進行添加的

url := ginSwagger.URL("http://localhost:8080/swagger/doc.json")
router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))
複製代碼

其中 url 定義了 swagger 的 doc.json 路徑，咱們能夠直接訪問該 json 來進行查看。

接下來就是完善文檔的時間。

在 main.go 中 main 方法上添加註釋。同時引入咱們生成 docs.go

package main

import (
	_ "GinHello/docs"
	"GinHello/initRouter"
)

// @title Gin swagger
// @version 1.0
// @description Gin swagger 示例項目

// @contact.name youngxhu
// @contact.url https://youngxhui.top
// @contact.email youngxhui@g mail.com

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8080
func main() {
    // 省略其餘代碼
}
複製代碼

上述的註釋基本都是很好理解的，不作過多解釋。

主要的項目介紹註釋就是這些，接下來進行咱們的接口方法註釋。

在咱們的 handler 中添加註釋

打開 articleHandler.go ,在 Insert 方法上添加。

// @Summary 提交新的文章內容
// @Id 1
// @Tags 文章
// @version 1.0
// @Accept application/x-json-stream
// @Param article body model.Article true "文章"
// @Success 200 object model.Result 成功後返回值
// @Failure 409 object model.Result 添加失敗
// @Router /article [post]
複製代碼

• @Summary 是對該接口的一個描述
• @Id 是一個全局標識符，全部的接口文檔中 Id 不能標註
• @Tags 是對接口的標註，同一個 tag 爲一組，這樣方便咱們整理接口
• @Version 代表該接口的版本
• @Accept 表示該該請求的請求類型
• @Param 表示參數 分別有如下參數 參數名詞 參數類型 數據類型 是否必須 註釋 屬性(可選參數),參數之間用空格隔開。
• @Success 表示請求成功後返回，它有如下參數 請求返回狀態碼，參數類型，數據類型，註釋
• @Failure 請求失敗後返回，參數同上
• @Router 該函數定義了請求路由而且包含路由的請求方式。

具體參數類型，數據類型等能夠查看官方文檔

其中文檔中沒有說明的地方這裏說明一下，關於 Param 的參數類型有如下幾種

• query 形如 \user?username=Jack&age=18
• body 須要將數據放到 body 中進行請求
• path 形如 \user\1

不一樣的參數類型對應的不一樣請求，請對應使用。

這樣咱們就完成了添加接口的文檔註釋。

咱們用通用的方法來完善一下根據 id 查詢數據的接口文檔。

在 GetOne 的方法上添加如上註釋。

// @Summary 經過文章 id 獲取單個文章內容
// @version 1.0
// @Accept application/x-json-stream
// @Param id path int true "id"
// @Success 200 object model.Result 成功後返回值
// @Router /article/{id} [get]
複製代碼

咱們對形如 /article/:id 的接口，最後的 id 經過 {} 包裹。

細心的小夥伴可能會發現咱們最後的返回結果爲 model.Result ，這是爲了咱們統一返回結果而新建的一個結構體，方便前端進行解析。具體函數以下

package model

type Result struct {
	Code    int         `json:"code" example:"000"`
	Message string      `json:"message" example:"請求信息"`
	Data    interface{} `json:"data" `
}
複製代碼

咱們在對 Result 中的 tag 會有 example ,這個仍舊是 swagger 的標籤，用來給該結構體一個示例。

同理，咱們能夠對以前的 article 進行註釋。

當咱們完成了全部的代碼註釋時，在控制檯中從新執行 swag init，它會根據咱們的註釋生成 docs.go 及其對應的 json 和 yaml 文件。

啓動咱們的項目，訪問 hppt://localhost:8080/swagger/index.html 就能夠查看咱們的文檔,效果以下

✍總結

經過本章節的學習，將咱們的項目和文檔相結合起來，反正要寫註釋，如今是一箭雙鵰，即完成了代碼註釋，也完成了項目文檔。

👨‍💻本章節代碼

Github

推薦閱讀

Gin(一):Hello
Gin(二):路由Router
Gin(三):模板tmpl
Gin(四):表單提交校驗和模型綁定
Gin(五):鏈接MySQL
Gin(六):文件的上傳
Gin(七):中間件的使用和定義
Gin(八):Cookie的使用
Gin(九):生成restful接口
Gin(十):集成 Swagger

我的公衆號

公衆號目前同步更新 Gin 系列文章，歡迎各位大佬關注： 代碼獵奇站