📜什么是swagger

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

通過 swagger 可以方便的生成接口文檔，方便前端進行查看和測試。

🔧安裝 swagger

在我們的項目中集成 swagger，以后項目的接口文檔便可以自動生成

安裝之前建議開啟go mod，使用goproxy下載

首先得安裝swagger

go get -u github.com/swaggo/swag/cmd/swag

驗證是否安裝成功$ swag -v

swag version v1.6.7復制代碼

🍔集成 swagger

安裝 gin-swagger$ go get -u github.com/swaggo/gin-swagger

$ go get -u github.com/swaggo/gin-swagger/swaggerFiles復制代碼

gin路由配置

在

router中添加路由，這個路由是對 swagger 的訪問地址來進行添加的

url := ginSwagger.URL("http://localhost:8080/swagger/doc.json")

router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

其中 url 定義了 swagger 的 doc.json 路徑，我們可以直接訪問該 json 來進行查看。

文檔配置

接下來就是完善文檔：

在 main.go 中 main 方法上添加注釋。

package main

import (

_ "GinHello/docs" //此處導入的是swag init 生成docs文件所在路徑

"GinHello/initRouter" //導入路由

)

// @title Gin swagger

// @version 1.0

// @description Gin swagger 示例項目

// @contact.name ganlei

// @contact.url https://juejin.im/user/1943592291283309

// @contact.email ganlei@uniontech.com

// @license.name Apache 2.0

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

// @host localhost:9090

func main() {

// 省略其他代碼

}

復制代碼

上述的注釋基本都是很好理解的，不做過多解釋。

主要的項目介紹注釋就是這些，接下來進行我們的接口方法注釋。

在我們的 handler 中添加注釋

Swagger 中需要將相應的注釋或注解編寫到方法上，再利用生成器自動生成說明文件

gin-swagger 給出的范例：

// @Summary Add a new pet to the store

// @Description get string by ID

// @Accept json

// @Produce json

// @Param some_id path int true "Some ID"

// @Success 200 {string} string "ok"

// @Failure 400 {object} web.APIError "We need ID!!"

// @Failure 404 {object} web.APIError "Can not find ID"

// @Router /testapi/get-string-by-int/{some_id} [get]復制代碼

我們可以參照 Swagger 的注解規范和范例去編寫

參考的注解請參見官方文檔。以確保獲取最新的 swag 語法

其中文檔中沒有說明的地方這里說明一下，關于 Param 的參數類型有以下幾種

query 形如 \user?username=Jack&age=18

body 需要將數據放到 body 中進行請求

path 形如 \user\1

不同的參數類型對應的不同請求，請對應使用。我們對路徑傳參形如 /user/:name?的接口，最后的 name 通過 {} 包裹。

通常@Success、@Failure返回結果可以包裝成一個結構體model.Result

package model

type Result struct {

Result bool `json:"result" example:"請求結果true或者false"`

Code int `json:"code" example:"000"`

Data interface{} `json:"data" `

}

復制代碼我們在對 Result 中的 tag 會有 example ,這個仍舊是 swagger 的標簽，用來給該結構體一個示例。

生成swagger對應的文件

當我們完成了所有的代碼注釋時，在控制臺中重新執行 swag init，它會根據我們的注釋生成 docs.go 及其對應的 json 和 yaml 文件。

需注意swag init指令需在項目根目錄下執行，這樣swag可以掃描整個項目中的swagger注釋

通過指令：

swag init -h

可以查看相關幫助，如果main.go函數不在項目根目錄的話，可以使用以下指令：

swag init -g ./../main.go - o ./docs復制代碼

這里用的是相對路徑，相對你的項目根目錄main.go所在位置

補充說明

main.go文件中的main上方注釋，有一個@BasePath,通常在使用域名解析時，以這種形式/api/v1訪問api接口

如果有遇到跨域問題，可以在Router中加上處理函數

//Cors ...允許跨域設置func Cors() gin.HandlerFunc { return func(c *gin.Context) { c.Header("Access-Control-Allow-Origin", "*") c.Header("Access-Control-Allow-Credentials", "false") c.Next() }}復制代碼

驗證

啟動我們的項目，訪問 hppt://localhost:9090/swagger/index.html就可以查看我們的文檔,效果如下

?總結

通過本章節的學習，將我們的項目和文檔相結合起來，反正要寫注釋，現在是一舉兩得，即完成了代碼注釋，也完成了項目文檔。

總結

以上是生活随笔為你收集整理的gin 生成api文档_gin-swagger 生成RESTful风格OpenAPI文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。