基於gin的golang web開發:整合swagger

陳巨集博發表於2020-11-20
在前後端分離的專案維護一份完整且及時更新的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是專案名。

現在訪問http://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

相關文章