Gin使用swagger生成接口文檔的代碼示例
什么是swagger
Swagger 是一個規(guī)范和完整的框架，用于生成、描述、調用和可視化 RESTful Web 服務。它使用 YAML 或 JSON 格式來定義 API 的結構，包括請求、響應、參數(shù)等信息。Swagger 的主要特點包括：
- 規(guī)范性：Swagger 定義了一套 API 描述的標準，使得開發(fā)者可以以統(tǒng)一的方式描述 API。
- 自動生成文檔：Swagger 可以自動生成 API 文檔，使得開發(fā)者和用戶可以快速了解 API 的使用方法。
- 交互式文檔：Swagger 提供了一個交互式的用戶界面，用戶可以直接在文檔中嘗試 API 調用。
- 代碼生成：Swagger 可以根據 API 描述自動生成服務器和客戶端的代碼，節(jié)省開發(fā)時間。
- 社區(qū)支持：Swagger 有廣泛的社區(qū)支持，許多開發(fā)者和公司都在使用它來構建和管理他們的 API。
- 工具鏈集成：Swagger 可以與許多開發(fā)工具和平臺集成，如 Spring Boot、.NET Core、Node.js 等。
- 版本控制：Swagger 支持 API 的版本控制，使得 API 的迭代更加靈活。
Swagger 現(xiàn)在通常與 OpenAPI Specification (OAS) 結合使用，后者是一個由 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ù)據
- 使用gin-swagger渲染在線接口文檔頁面
添加注釋
在程序入口main函數(shù)上以注釋的方式寫下項目相關介紹信息。
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 這里寫接口服務的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ù)據
在項目根目錄中運行命令：swag init，將會解析注解并生成所需的文件（doc文件夾和docs.go,swagger.json,swagger.yaml）
swag init
執(zhí)行完命令后，會生成以下文件
./docs ├── docs.go ├── swagger.json └── swagger.yaml
然后在項目代碼中注冊路由的地方按如下方式引入gin-swagger相關內容：
import ( _ "project/docs" // 千萬不要忘了導入把你上一步生成的docs gs "github.com/swaggo/gin-swagger" "github.com/swaggo/gin-swagger/swaggerFiles" "github.com/gin-gonic/gin" )
注冊swagger api相關路由
r.GET("/swagger/*any", gs.WrapHandler(swaggerFiles.Handler))
項目程序運行起來，打開瀏覽器訪問http://localhost:8080/swagger/index.html就能看到Swagger Api文檔了。
gin-swagger同時還提供了DisablingWrapHandler函數(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
到此這篇關于Gin使用swagger生成接口文檔的代碼示例的文章就介紹到這了,更多相關Gin swagger接口文檔內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！
相關文章
Golang兩行代碼實現(xiàn)發(fā)送釘釘機器人消息
創(chuàng)建一個釘釘機器人必須使用加簽，本文通過Golang兩行代碼實現(xiàn)發(fā)送釘釘機器人消息，本文給大家介紹的非常詳細，感興趣的朋友跟隨小編一起看看吧2021-12-12
本文主要介紹了GO 切片刪除元素,根據要刪除元素的位置有三種情況,分別是從開頭位置刪除、從中間位置刪除和從尾部刪除,具有一定的參考價值,感興趣的可以了解一下2024-08-08
這篇文章主要介紹了golang官方嵌入文件到可執(zhí)行程序,本文通過示例代碼給大家介紹的非常詳細，對大家的學習或工作具有一定的參考借鑒價值，需要的朋友可以參考下2021-02-02
這篇文章主要介紹了golang 獲取字符串長度的案例，具有很好的參考價值，希望對大家有所幫助。一起跟隨小編過來看看吧2020-12-12
這篇文章主要介紹了go語言的四數(shù)相加等于指定數(shù)算法的操作，具有很好的參考價值，希望對大家有所幫助。一起跟隨小編過來看看吧2021-04-04
如何使用Golang創(chuàng)建與讀取Excel文件
我最近工作忙于作圖,圖表,需要自己準備數(shù)據源,所以經常和Excel打交道,下面這篇文章主要給大家介紹了關于如何使用Golang創(chuàng)建與讀取Excel文件的相關資料,需要的朋友可以參考下2022-07-07
鏈路追蹤是指在分布式系統(tǒng)中,將一次請求的處理過程進行記錄并聚合展示的一種方法,目的是將一次分布式請求的調用情況集中在一處展示,本文將介紹golang如何使用jaeger進行鏈路追蹤,需要的朋友可以參考下2024-06-06
這篇文章在 go-kratos 官方的 layout 項目的整潔架構基礎上,實現(xiàn)優(yōu)雅的數(shù)據庫事務操作,需要的朋友可以參考下2024-08-08
這篇文章主要介紹了詳解使用Go添加Nginx代理的方法示例,文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧2019-11-11
Go實現(xiàn)的cron 表達式的基本語法跟linux 中的 crontab基本是類似的,下面這篇文章主要給大家介紹了關于golang定時任務cron項目實操的相關資料,文中通過示例代碼介紹的非常詳細,需要的朋友可以參考下2022-12-12