Gin使用swagger生成接口文檔的代碼示例
什么是swagger
Swagger 是一個規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful Web 服務(wù)。它使用 YAML 或 JSON 格式來定義 API 的結(jié)構(gòu)，包括請求、響應(yīng)、參數(shù)等信息。Swagger 的主要特點包括：
- 規(guī)范性：Swagger 定義了一套 API 描述的標準，使得開發(fā)者可以以統(tǒng)一的方式描述 API。
- 自動生成文檔：Swagger 可以自動生成 API 文檔，使得開發(fā)者和用戶可以快速了解 API 的使用方法。
- 交互式文檔：Swagger 提供了一個交互式的用戶界面，用戶可以直接在文檔中嘗試 API 調(diào)用。
- 代碼生成：Swagger 可以根據(jù) API 描述自動生成服務(wù)器和客戶端的代碼，節(jié)省開發(fā)時間。
- 社區(qū)支持：Swagger 有廣泛的社區(qū)支持，許多開發(fā)者和公司都在使用它來構(gòu)建和管理他們的 API。
- 工具鏈集成：Swagger 可以與許多開發(fā)工具和平臺集成，如 Spring Boot、.NET Core、Node.js 等。
- 版本控制：Swagger 支持 API 的版本控制，使得 API 的迭代更加靈活。
Swagger 現(xiàn)在通常與 OpenAPI Specification (OAS) 結(jié)合使用，后者是一個由 Linux 基金會支持的開放標準，用于描述 API。Swagger 的工具和生態(tài)系統(tǒng)現(xiàn)在也支持 OAS。
swagger安裝
$ go get -u github.com/swaggo/swag/cmd/swag # 1.16 及以上版本 $ go install github.com/swaggo/swag/cmd/swag@latest
gin-swagger
安裝
go get -u github.com/swaggo/gin-swagger
使用
想要使用gin-swagger為你的代碼自動生成接口文檔，一般需要下面三個步驟：
- 按照swagger要求給接口代碼添加聲明式注釋，具體參照聲明式注釋格式。
- 使用swag工具掃描代碼自動生成API接口文檔數(shù)據(jù)
- 使用gin-swagger渲染在線接口文檔頁面
添加注釋
在程序入口main函數(shù)上以注釋的方式寫下項目相關(guān)介紹信息。
package main
// @title 這里寫標題
// @version 1.0
// @description 這里寫描述信息
// @termsOfService http://swagger.io/terms/
// @contact.name 這里寫聯(lián)系人信息
// @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 這里寫接口服務(wù)的host
// @BasePath 這里寫base path
func main() {
r := gin.New()
// liwenzhou.com ...
r.Run()
}
在你代碼中處理請求的接口函數(shù)（通常位于controller層）按如下方式寫上注釋：
// GetCommunityHandler 獲取社區(qū)列表
// @Summary 獲取社區(qū)列表
// @Description 獲取社區(qū)列表
// @Tags 社區(qū)列表
// @Accept json
// @Produce json
// @Param Authorization header string true "Bearer 用戶令牌"
// @Success 200 {object} models.GetCommunityListParams "成功"
// @Router /community [get]
// @Request Body models.GetCommunityListParams "社區(qū)列表"
func GetCommunityHandler(c *gin.Context) {
// 獲取社區(qū)列表 (Community_id, Community_name) list
list, err := communityLg.GetCommunityList()
if err != nil {
api.ResponseErrorWithMsg(c, 200, "獲取社區(qū)列表失敗")
return
}
api.ResponseSuccess(c, list)
}
生成接口文檔數(shù)據(jù)
在項目根目錄中運行命令：swag init，將會解析注解并生成所需的文件（doc文件夾和docs.go,swagger.json,swagger.yaml）
swag init
執(zhí)行完命令后，會生成以下文件
./docs ├── docs.go ├── swagger.json └── swagger.yaml
然后在項目代碼中注冊路由的地方按如下方式引入gin-swagger相關(guān)內(nèi)容：
import ( _ "project/docs" // 千萬不要忘了導(dǎo)入把你上一步生成的docs gs "github.com/swaggo/gin-swagger" "github.com/swaggo/gin-swagger/swaggerFiles" "github.com/gin-gonic/gin" )
注冊swagger api相關(guān)路由
r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))
項目程序運行起來，打開瀏覽器訪問http://localhost:8080/swagger/index.html就能看到Swagger Api文檔了。
gin-swagger同時還提供了DisablingWrapHandler函數(shù)，方便我們通過設(shè)置某些環(huán)境變量來禁用Swagger。例如：
r.GET("/swagger/*any", gs.DisablingWrapHandler(swaggerFiles.Handler, "NAME_OF_ENV_VARIABLE"))
可能遇到的問題
在我使用時發(fā)現(xiàn)在執(zhí)行swag init時，會出現(xiàn)找不到gorm.Model的情況。
解決方案：
在命令行加上 --parseDependency --parseInternal
swag init --parseDependency --parseInternal
到此這篇關(guān)于Gin使用swagger生成接口文檔的代碼示例的文章就介紹到這了,更多相關(guān)Gin swagger接口文檔內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！
相關(guān)文章
Go語言中make和new函數(shù)的用法與區(qū)別
這篇文章介紹了Go語言中make和new函數(shù)的用法與區(qū)別，文中通過示例代碼介紹的非常詳細。對大家的學(xué)習(xí)或工作具有一定的參考借鑒價值，需要的朋友可以參考下2022-07-07
函數(shù)是?Golang?中非常重要的組成部分之一，它們提供了代碼的可重用性和組織性。在本文中，我們將深入了解?Golang?函數(shù)的多個方面，希望對大家有所幫助2023-04-04
這篇文章主要為大家介紹了Go?Web編程添加服務(wù)器錯誤日志和訪問日志的示例解析，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進步，早日升職加薪2022-06-06
這篇文章主要介紹了Mac GoLand打不開(閃退)也不報錯的解決方案，具有很好的參考價值，希望對大家有所幫助。一起跟隨小編過來看看吧2021-04-04
Golang簡單實現(xiàn)http的server端和client端
Http 服務(wù)是基于 Tcp 的應(yīng)用層的實現(xiàn),也是最常見的網(wǎng)絡(luò)協(xié)議之一。本文主要介紹了Golang簡單實現(xiàn)http的server端和client端，感興趣的可以了解一下2021-06-06
golang中判斷請求是http還是https獲取當前訪問地址
這篇文章主要為大家介紹了golang中判斷請求是http還是https獲取當前訪問地址示例詳解,有需要的朋友可以借鑒參考下,希望能夠有所幫助,祝大家多多進步,早日升職加薪2023-10-10
RWMutex是一個支持并行讀串行寫的讀寫鎖。RWMutex具有寫操作優(yōu)先的特點，寫操作發(fā)生時，僅允許正在執(zhí)行的讀操作執(zhí)行，后續(xù)的讀操作都會被阻塞。本文就來從源碼解析一下RWMutex的使用2023-03-03
相信大家都知道不同語言之間的通信方式有很多種，這篇文章詳細的介紹了PHP與Go語言之間如何通信，有需要的朋友們可以參考借鑒，下面來一起看看吧。2016-10-10
vscode安裝go插件時,由于各種原因,在安裝插件時總是失敗,下面這篇文章主要給大家介紹了關(guān)于VS?Code安裝go插件失敗原因分析以及解決的相關(guān)資料,文中通過實例代碼介紹的非常詳細,需要的朋友可以參考下2022-09-09
這篇文章主要介紹了go-micro集成鏈路跟蹤的方法和中間件原理,關(guān)于Http或者說是Restful服務(wù)的鏈路跟蹤，go-micro的httpClient支持CallWrapper，可以用WrapCall來添加鏈路跟蹤的CallWrapper，本文給大家介紹的非常詳細，需要的朋友參考下吧2022-05-05