Gin + Swagger快速生成API文件

語言: CN / TW / HK
時間 2021-10-05 22:15:13
主題:

小知識，大挑戰！本文正在參與「程式設計師必備小知識」創作活動。

本文已參與 「掘力星計劃」 ，贏取創作大禮包，挑戰創作激勵金。

一 背景

在restful前後端專案進行介面對接的時候，需要有明確的介面文件，此時單獨針對介面編寫介面文件，耗時耗力，切程式碼修改後，還需要維護介面文件，此時容易出現文件不統一的情況，將介面文件直接寫在程式碼中是一種比較好的方式。

swagger就是解決這種問題，開發人員只需要按照特定規範在編寫介面程式碼時寫上swagger註釋，利用swagger生成介面文件。

二 Swagger UI簡介

Swagger 是一個 API 生成工具，可以生成文件。 Swagger 是通過編寫 yaml 和 json 來實現文件化。並且可以進行測試等工作。

通過 swagger 可以方便的生成介面文件，方便前端進行檢視和測試。

三 專案整合

3.1 安裝swag

shell $ go get github.com/swaggo/swag/cmd/swag

3.2 生成檔案

首次生成相關檔案，後期程式碼修改過，新增swag註解後，也需要

```shell

在go 專案中（包含main.go）的目錄，使用swag init命令生成相關檔案。

$ swag init 2021/09/23 16:32:23 Generate swagger docs.... 2021/09/23 16:32:23 Generate general API Info, search dir:./ 2021/09/23 16:32:26 create docs.go at docs/docs.go 2021/09/23 16:32:26 create swagger.json at docs/swagger.json 2021/09/23 16:32:26 create swagger.yaml at docs/swagger.yaml

```

3.3 安裝gin-swagger

shell $ go get -u github.com/swaggo/gin-swagger $ go get -u github.com/swaggo/gin-swagger/swaggerFiles

3.4 整合

  • 引入生成的docs包
  • 在具體介面上根據規範swag編寫介面描述
  • 在路由中進行引入
  • 再次執行swag init 更新介面
  • 執行應用後，瀏覽器訪問：http://localhost:8887/swagger/index.html

```shell package main

import ( "github.com/gin-gonic/gin" swaggerFiles "github.com/swaggo/files" ginSwagger "github.com/swaggo/gin-swagger"

_ "github.com/swaggo/gin-swagger/example/basic/docs" // docs is generated by Swag CLI, you have to import it.

)

// @title Swagger Example API // @version 1.0 // @description This is a sample server Petstore server. // @termsOfService http://swagger.io/terms/

// @contact.name API Support // @contact.url http://www.swagger.io/support // @contact.email [email protected]

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

// @host petstore.swagger.io // @BasePath /v2 func main() { r := gin.New()

url := ginSwagger.URL("http://localhost:8080/swagger/doc.json") // The url pointing to API definition
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

r.Run()

} ```

四 不同型別

4.1 請求

4.1.1 url引數

go // @Param id path int true "ID" //url引數：（name；引數型別[query(?id=),path(/123)]；資料型別；required；引數描述）

4.1.2 body引數

例如json

go // @Param data body models.RegistryAuth true "請示引數data"

4.2 返回

4.2.1 字串

// @Success 200 {string} json "{"msg":"ok"}"

4.2.2 結構體返回

// @Success 200 {object} models.Response "請求成功" // @Failure 400 {object} models.ResponseErr "請求錯誤" // @Failure 500 {object} models.ResponseErr "內部錯誤"

五 實戰

5.1 main函式新增全域性

```go // @title smartkm_api_image Swagger Example // @version 1.0 // @description This is a sample server Petstore server. // @termsOfService http://swagger.io/terms/

// @contact.name API Support // @contact.url http://www.swagger.io/support // @contact.email [email protected]

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

// @host petstore.swagger.io // @BasePath / func main() { // 啟動服務 run() }

```

5.2 函式級別

5.2.1 Get請求

go // @Summary 檢視遷移任務詳細資訊 // @Description 檢視遷移任務詳細資訊 // @Accept json // @Produce json // @Param task_id path string true "task_id" // @Success 200 {object} models.Response "請求成功" // @Failure 400 {object} models.ResponseErr "請求錯誤" // @Failure 500 {object} models.ResponseErr "內部錯誤" // @Router /task [get]

5.2.2 Post請求

go // @Summary 建立映象遷移任務 // @Description 建立映象遷移任務 // @Accept json // @Produce json // @Param data body models.CreateTaskReq true "請示引數data" // @Success 200 {object} models.Response "請求成功" // @Failure 400 {object} models.ResponseErr "請求錯誤" // @Failure 500 {object} models.ResponseErr "內部錯誤" // @Router /task [post]

5.2.3 Delete請求

go // @Summary 刪除映象遷移任務 // @Description 刪除映象遷移任務 // @Accept json // @Produce json // @Param data body models.TaskReq true "請示引數data" // @Success 200 {object} models.Response "請求成功" // @Failure 400 {object} models.ResponseErr "請求錯誤" // @Failure 500 {object} models.ResponseErr "內部錯誤" // @Router /task [delete]

注意事項

  • 在路由新增swagger的時候，需要引入專案生成的docs包
  • 假如func方法頭標註的swagger註釋不正確，在執行swag init會報錯，自行根據報錯資訊去修改；
  • 訪問swagger控制檯報錯404 page not found，是因為沒有新增swagger的路由
  • 訪問swagger控制檯報錯Failed to load spec，是因為沒有import引入執行swag init生成的swagger的docs資料夾；

參考連結

  • http://studygolang.com/articles/12354
  • http://github.com/go-swagger/go-swagger
  • http://github.com/swaggo/gin-swagger
「」
「」