在前後端分離的專案維護一份完整且及時更新的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中。程式碼如下： ```golang 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頁面。 ### 編寫介面註釋資訊 ```golang 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][source] [source]: https://www.huaface.com/art