Gin + Swagger快速生成API文檔

一 背景

在restful前后端項(xiàng)目進(jìn)行接口對(duì)接的時(shí)候，需要有明確的接口文檔，此時(shí)單獨(dú)針對(duì)接口編寫接口文檔，耗時(shí)耗力，切代碼修改后，還需要維護(hù)接口文檔，此時(shí)容易出現(xiàn)文檔不統(tǒng)一的情況，將接口文檔直接寫在代碼中是一種比較好的方式。

swagger就是解決這種問題，開發(fā)人員只需要按照特定規(guī)范在編寫接口代碼時(shí)寫上swagger注釋，利用swagger生成接口文檔。

二 Swagger UI簡介

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

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

三 項(xiàng)目集成

3.1 安裝swag

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

3.2 生成文件

首次生成相關(guān)文件，后期代碼修改過，添加swag注解后，也需要

# 在go 項(xiàng)目中（包含main.go）的目錄，使用swag init命令生成相關(guān)文件。 $ 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

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

3.4 集成

引入生成的docs包

在具體接口上根據(jù)規(guī)范swag編寫接口描述

在路由中進(jìn)行引入

再次執(zhí)行swag init 更新接口

運(yùn)行應(yīng)用后，瀏覽器訪問：http://localhost:8887/swagger/index.html

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 support@swagger.io // @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參數(shù)

// @Param id path int true "ID" //url參數(shù)：（name；參數(shù)類型[query(?id=),path(/123)]；數(shù)據(jù)類型；required；參數(shù)描述）

4.1.2 body參數(shù)

例如json

// @Param data body models.RegistryAuth true "請示參數(shù)data"

4.2 返回

4.2.1 字符串

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

4.2.2 結(jié)構(gòu)體返回

// @Success 200 {object} models.Response "請求成功" // @Failure 400 {object} models.ResponseErr "請求錯(cuò)誤" // @Failure 500 {object} models.ResponseErr "內(nèi)部錯(cuò)誤"

五 實(shí)戰(zhàn)

5.1 main函數(shù)添加全局

// @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 support@swagger.io // @license.name Apache 2.0 // @license.url http://www.apache.org/licenses/LICENSE-2.0.html // @host petstore.swagger.io // @BasePath / func main() { // 啟動(dòng)服務(wù) run() }

5.2 函數(shù)級(jí)別

5.2.1 Get請求

// @Summary 查看遷移任務(wù)詳細(xì)信息 // @Description 查看遷移任務(wù)詳細(xì)信息 // @Accept json // @Produce json // @Param task_id path string true "task_id" // @Success 200 {object} models.Response "請求成功" // @Failure 400 {object} models.ResponseErr "請求錯(cuò)誤" // @Failure 500 {object} models.ResponseErr "內(nèi)部錯(cuò)誤" // @Router /task [get]

5.2.2 Post請求

// @Summary 創(chuàng)建鏡像遷移任務(wù) // @Description 創(chuàng)建鏡像遷移任務(wù) // @Accept json // @Produce json // @Param data body models.CreateTaskReq true "請示參數(shù)data" // @Success 200 {object} models.Response "請求成功" // @Failure 400 {object} models.ResponseErr "請求錯(cuò)誤" // @Failure 500 {object} models.ResponseErr "內(nèi)部錯(cuò)誤" // @Router /task [post]

5.2.3 Delete請求

// @Summary 刪除鏡像遷移任務(wù) // @Description 刪除鏡像遷移任務(wù) // @Accept json // @Produce json // @Param data body models.TaskReq true "請示參數(shù)data" // @Success 200 {object} models.Response "請求成功" // @Failure 400 {object} models.ResponseErr "請求錯(cuò)誤" // @Failure 500 {object} models.ResponseErr "內(nèi)部錯(cuò)誤" // @Router /task [delete]

注意事項(xiàng)

在路由添加swagger的時(shí)候，需要引入項(xiàng)目生成的docs包

假如func方法頭標(biāo)注的swagger注釋不正確，在執(zhí)行swag init會(huì)報(bào)錯(cuò)，自行根據(jù)報(bào)錯(cuò)信息去修改；

訪問swagger控制臺(tái)報(bào)錯(cuò)404 page not found，是因?yàn)闆]有添加swagger的路由

訪問swagger控制臺(tái)報(bào)錯(cuò)Failed to load spec，是因?yàn)闆]有import引入執(zhí)行swag init生成的swagger的docs文件夾；

參考鏈接

https://studygolang.com/articles/12354

https://github.com/go-swagger/go-swagger

https://github.com/swaggo/gin-swagger

API

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實(shí)的內(nèi)容，請聯(lián)系我們jiasou666@gmail.com 處理，核實(shí)后本網(wǎng)站將在24小時(shí)內(nèi)刪除侵權(quán)內(nèi)容。

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實(shí)的內(nèi)容，請聯(lián)系我們jiasou666@gmail.com 處理，核實(shí)后本網(wǎng)站將在24小時(shí)內(nèi)刪除侵權(quán)內(nèi)容。