什么是swagger

Swagger 是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful Web 服務(wù)。它使用 YAML 或 JSON 格式來定義 API 的結(jié)構(gòu)，包括請(qǐng)求、響應(yīng)、參數(shù)等信息。Swagger 的主要特點(diǎn)包括：

• 規(guī)范性：Swagger 定義了一套 API 描述的標(biāo)準(zhǔn)，使得開發(fā)者可以以統(tǒng)一的方式描述 API。
• 自動(dòng)生成文檔：Swagger 可以自動(dòng)生成 API 文檔，使得開發(fā)者和用戶可以快速了解 API 的使用方法。
• 交互式文檔：Swagger 提供了一個(gè)交互式的用戶界面，用戶可以直接在文檔中嘗試 API 調(diào)用。
• 代碼生成：Swagger 可以根據(jù) API 描述自動(dòng)生成服務(wù)器和客戶端的代碼，節(jié)省開發(fā)時(shí)間。
• 社區(qū)支持：Swagger 有廣泛的社區(qū)支持，許多開發(fā)者和公司都在使用它來構(gòu)建和管理他們的 API。
• 工具鏈集成：Swagger 可以與許多開發(fā)工具和平臺(tái)集成，如 Spring Boot、.NET Core、Node.js 等。
• 版本控制：Swagger 支持 API 的版本控制，使得 API 的迭代更加靈活。

Swagger 現(xiàn)在通常與 OpenAPI Specification (OAS) 結(jié)合使用，后者是一個(gè)由 Linux 基金會(huì)支持的開放標(biāo)準(zhǔn)，用于描述 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為你的代碼自動(dòng)生成接口文檔，一般需要下面三個(gè)步驟：

• 按照swagger要求給接口代碼添加聲明式注釋，具體參照聲明式注釋格式。
• 使用swag工具掃描代碼自動(dòng)生成API接口文檔數(shù)據(jù)
• 使用gin-swagger渲染在線接口文檔頁面

添加注釋

在程序入口main函數(shù)上以注釋的方式寫下項(xiàng)目相關(guān)介紹信息。

package main

// @title 這里寫標(biāo)題
// @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()
}

在你代碼中處理請(qǐng)求的接口函數(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ù)

在項(xiàng)目根目錄中運(yùn)行命令：swag init，將會(huì)解析注解并生成所需的文件（doc文件夾和docs.go,swagger.json,swagger.yaml）

swag init

執(zhí)行完命令后，會(huì)生成以下文件

./docs
├── docs.go
├── swagger.json
└── swagger.yaml

然后在項(xiàng)目代碼中注冊路由的地方按如下方式引入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))

項(xiàng)目程序運(yùn)行起來，打開瀏覽器訪問http://localhost:8080/swagger/index.html就能看到Swagger Api文檔了。

gin-swagger同時(shí)還提供了DisablingWrapHandler函數(shù)，方便我們通過設(shè)置某些環(huán)境變量來禁用Swagger。例如：

r.GET("/swagger/*any", gs.DisablingWrapHandler(swaggerFiles.Handler, "NAME_OF_ENV_VARIABLE"))

可能遇到的問題

在我使用時(shí)發(fā)現(xiàn)在執(zhí)行swag init時(shí)，會(huì)出現(xiàn)找不到gorm.Model的情況。

解決方案：

在命令行加上 --parseDependency --parseInternal

swag init --parseDependency --parseInternal

到此這篇關(guān)于Gin使用swagger生成接口文檔的代碼示例的文章就介紹到這了,更多相關(guān)Gin swagger接口文檔內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論