📜什么是swagger

Swagger 是一個(gè) API 生成工具，可以生成文檔。 Swagger 是通過編寫 yaml 和 json 來實(shí)現(xiàn)文檔化。并且可以進(jìn)行測試等工作。

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

🔧安裝 swagger

在我們的項(xiàng)目中集成 swagger，以后項(xiàng)目的接口文檔便可以自動(dòng)生成

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

首先得安裝swagger

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

驗(yàn)證是否安裝成功$ swag -v

swag version v1.6.7復(fù)制代碼

🍔集成 swagger

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

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

gin路由配置

在

router中添加路由，這個(gè)路由是對 swagger 的訪問地址來進(jìn)行添加的

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

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

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

文檔配置

接下來就是完善文檔：

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

package main

import (

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

"GinHello/initRouter" //導(dǎo)入路由

)

// @title Gin swagger

// @version 1.0

// @description Gin swagger 示例項(xiàng)目

// @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() {

// 省略其他代碼

}

復(fù)制代碼

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

主要的項(xiàng)目介紹注釋就是這些，接下來進(jìn)行我們的接口方法注釋。

在我們的 handler 中添加注釋

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

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]復(fù)制代碼

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

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

其中文檔中沒有說明的地方這里說明一下，關(guān)于 Param 的參數(shù)類型有以下幾種

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

body 需要將數(shù)據(jù)放到 body 中進(jìn)行請求

path 形如 \user\1

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

通常@Success、@Failure返回結(jié)果可以包裝成一個(gè)結(jié)構(gòu)體model.Result

package model

type Result struct {

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

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

Data interface{} `json:"data" `

}

復(fù)制代碼我們在對 Result 中的 tag 會(huì)有 example ,這個(gè)仍舊是 swagger 的標(biāo)簽，用來給該結(jié)構(gòu)體一個(gè)示例。

生成swagger對應(yīng)的文件

當(dāng)我們完成了所有的代碼注釋時(shí)，在控制臺(tái)中重新執(zhí)行 swag init，它會(huì)根據(jù)我們的注釋生成 docs.go 及其對應(yīng)的 json 和 yaml 文件。

需注意swag init指令需在項(xiàng)目根目錄下執(zhí)行，這樣swag可以掃描整個(gè)項(xiàng)目中的swagger注釋

通過指令：

swag init -h

可以查看相關(guān)幫助，如果main.go函數(shù)不在項(xiàng)目根目錄的話，可以使用以下指令：

swag init -g ./../main.go - o ./docs復(fù)制代碼

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

補(bǔ)充說明

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

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

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

驗(yàn)證

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

?總結(jié)

通過本章節(jié)的學(xué)習(xí)，將我們的項(xiàng)目和文檔相結(jié)合起來，反正要寫注釋，現(xiàn)在是一舉兩得，即完成了代碼注釋，也完成了項(xiàng)目文檔。

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。