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設定介面的路由。