基於gin的golang web開發：集成swagger

2020 年 11 月 20 日
筆記
gin, golang, WEB

在前後端分離的項目維護一份完整且及時更新的api文檔會極大的提高我們的工作效率，傳統項目中接口文檔都是由後端開發手寫的，這種文檔很難保證及時性，久而久之便失去了參考意義。swagger給我們提供了一種新的維護文檔的方式，在gin中只需要編寫一些注釋即可生成一份可交互的接口文檔。

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

引入這些包之後就可以通過給方法寫注釋的方式生成接口文檔。github.com/swaggo/swag/cmd/swag中包含一個用於生成接口文檔的命令行工具swag，github.com/swaggo/gin-swagger是一個gin中間件，github.com/swaggo/files中包含了swagger UI的一些如css、js等必要的文件。

與gin集成

我們需要在代碼中引入必要的包，並且在main方法上增加兩個必填的通用API注釋title和version，這兩個注釋分別表示應用程序的名稱和應用程序API的版本，這些內容會顯示在swagger ui中。代碼如下：

package main

import (
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	_ "proj/docs"
)

// @title 用戶中心API
// @version 1.0
func main() {
	engine := gin.Default()

	url := ginSwagger.URL("/swagger/doc.json")
	engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

	_ = engine.Run(":8081")
}

我們在代碼中定義doc.json的文件地址為/swagger/doc.json，swagger ui會解析這個地址渲染頁面。緊接着定義路由規則/swagger/*any全部經由ginSwagger.WrapHandler中間件處理。

在包含main.go文件的項目根目錄運行swag init。這將會解析注釋並生成docs/docs.go和swagger所需的文件，最後引用docs_ "proj/docs"，proj是項目名。

現在訪問//localhost:8081/swagger/index.html就會看到熟悉的swagger ui頁面。

編寫接口注釋信息

type SysRole struct {
	Id          int64       `json:"id"`
	Name        null.String `json:"name" swaggertype:"string"` // 角色名
	Description null.String `json:"description" swaggertype:"string"`
	Available   null.Int    `json:"available" swaggertype:"integer"`
	CreateTime  null.Time   `json:"create_time" db:"create_time" swaggertype:"string"` // 添加時間
	UpdateTime  null.Time   `json:"update_time" db:"update_time" swaggertype:"string"` // 更新時間
}

// 角色列表
// @Summary 角色列表
// @Description 角色列表
// @Tags 角色
// @Success 200 {array} SysRole
// @Router /roles [get]
func RoleList(c *gin.Context) {
	list := sysRole.GetAllRole()

	c.JSON(http.StatusOK, list)
}

我們分別在model和handler方法上增加一些必要的信息。

Name字段在SysRole結構體中的類型為null.String，但是swag init生成文檔時因為不能自動解析null包產生如下錯誤信息：

ParseComment error in file xxxxxxx.go :cannot find package path of type: null.String

一種解決方案是命令改為執行swag init --parseDependency解析外部依賴，這個命令需要解析大量的外部依賴運行時間很長，而且似乎也並不能解決所有問題。更推薦使用以上代碼中的swaggertype標籤來解決問題。swaggertype標籤指定swagger中使用的類型，如int類型字段設置標籤為swaggertype:"integer"。

handler方法上增加註釋描述當前接口的信息。@Summary和@Description設置接口的概要和描述信息。@Tags設置接口的分組，例如有接口 /roles 和 /roles/[:id] 都返回角色相關的信息，那麼這兩個handler的注釋可以統一設置為 @Tags 角色。@Success設置接口成功返回的內容，這裡設置為SysRole數組，當然還有@Failure設置接口失敗的返回結果。@Router設置接口的路由。

文章出處：基於gin的golang web開發：集成swagger

Tags: gin golang WEB