Golang | Web开发之Gin使用swag生成项目的Swagger API接口文档

0x00 在你使用Gin开发Web时添加swagger

1. swagger简单介绍

官网介绍: Swagger工具是由原始“Swagger”规范背后的团队开发的。Swagger提供了最强大和最容易使用的工具，以充分利用OpenAPI规范。

使用 Swagger 开源和专业工具集简化用户、团队和企业的 API 开发, 并且帮助开发者完善接口设计，接口开发、接口文档、接口测试、API模拟和虚拟化、以及接口治理与接口监控。

官网地址: https://swagger.io/
文档地址: https://swagger.io/docs/specification/2-0/basic-structure/
接口规范: https://swagger.io/resources/open-api/

此处由于是在Golang中的Web框架Gin中使用Swagger，所以在下一章节中暂时介绍如何在Golang的Web框架Gin中使用Swagger。

2. swag、gin-swagger项目安装

描述: go-swagger 是一个主要生成或分析源代码的工具，我们可以使用 go-swagger 工具为Gin项目使用Swagger 2.0自动生成RESTful API文档。

项目功能

• Basic Structure
• API Host and Base Path
• Paths and Operations
• Describing Parameters
• Describing Request Body
• Describing Responses
• MIME Types
• Authentication
  • Basic Authentication
  • API Keys
• Adding Examples
• File Upload
• Enums
• Grouping Operations With Tags
• Swagger Extensions (开发中)

项目地址:

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

支持的 Web Frameworks:

gin
echo
buffalo
net/http
gorilla/mux
go-chi/chi
flamingo
fiber
atreugo
hertz

安装实践

1.首先需要安装Go语言环境下 swagger相关工具,可以使用以下命令安装，参考地址 ( https://goswagger.io/install.html)

# Swagger 2.0 implementation for go 

# - go-swagger 工具为 Go 程序生成 swagger 相关文档 （手动配yaml文件）

# 从Go 1.17开始，不赞成使用Go get安装可执行文件建议使用 go install

go install github.com/go-swagger/go-swagger/cmd/swagger@latest

# 不建议

# go get -u github.com/go-swagger/go-swagger/cmd/swagger



# - swag 工具将 Go 注释转换为 Swagger 文档 2.0，使您可以快速与现有的 Go 项目集成（使用 Swagger UI，此处用于go-gin项目

go install github.com/swaggo/swag/cmd/swag@latest

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

除此此外我们还可以手动编译：

cd D:\Study\Go\package\pkg\mod\github.com\swaggo\swag@v1.16.1\cmd\swag

go build -o swag.exe ./main.go

2.此处由于我是 windows 其安装目录如下, 通过CMD命令或者PowerShell查看.

# CMD

> dir "%GOPATH%/bin/" /B  

swag

swagger.exe



# PowerShell

> ls $env:GOPATH/bin

Directory: D:\Study\Go\package\bin

-a---           2023/6/12    14:59       14539264 swag.exe

-a---           2023/6/13     9:49       24419840 swagger.exe

其他安装方式，例如二进制方式安装或者容器方式安装。

• 二进制方式: Go-Swagger 二进制文件下载 [ https://github.com/go-swagger/go-swagger/tags ] ，swag 二进制文件下载 [ https://github.com/swaggo/swag/releases ] ，请注意对应系统版本 .

Docker 安装方式

# 镜像拉取

docker pull quay.io/goswagger/swagger

# 在 Winwdows 中即在Go开发项目下执行

docker run --rm -it --env GOPATH=/go -v %CD%:/go/src -w /go/src quay.io/goswagger/swagger

# 在 Linux 中

docker run --rm -it --env GOPATH=/go -v $pwd:/go/src -w /go/src quay.io/goswagger/swagger

3. 如何在Gin使用Swagger生成API接口文档?

1. 在你的Go-gin项目main.go代码中的 package main 下添加通用API注释, 注释解析。

package main



import (

	"errors"

	"net/http"



	"github.com/gin-gonic/gin"

	"github.com/swaggo/swag/example/celler/controller"

	_ "github.com/swaggo/swag/example/celler/docs"

	"github.com/swaggo/swag/example/celler/httputil"



	swaggerFiles "github.com/swaggo/files"

	ginSwagger "github.com/swaggo/gin-swagger"

)



//	@title			Swagger Example API

//	@version		1.0

//	@description	This is a sample server celler 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		localhost:8080

//	@BasePath	/api/v1



//	@securityDefinitions.basic	BasicAuth



//	@securityDefinitions.apikey	ApiKeyAuth

//	@in							header

//	@name						Authorization

//	@description				Description for what is this security definition being used



//	@securitydefinitions.oauth2.application	OAuth2Application

//	@tokenUrl								https://example.com/oauth/token

//	@scope.write							Grants write access

//	@scope.admin							Grants read and write access to administrative information



//	@securitydefinitions.oauth2.implicit	OAuth2Implicit

//	@authorizationUrl						https://example.com/oauth/authorize

//	@scope.write							Grants write access

//	@scope.admin							Grants read and write access to administrative information



//	@securitydefinitions.oauth2.password	OAuth2Password

//	@tokenUrl								https://example.com/oauth/token

//	@scope.read								Grants read access

//	@scope.write							Grants write access

//	@scope.admin							Grants read and write access to administrative information



//	@securitydefinitions.oauth2.accessCode	OAuth2AccessCode

//	@tokenUrl								https://example.com/oauth/token

//	@authorizationUrl						https://example.com/oauth/authorize

//	@scope.admin							Grants read and write access to administrative information



func main() {

	r := gin.Default()

	c := controller.NewController()

	v1 := r.Group("/api/v1")

	{

		admin := v1.Group("/admin")	{

			admin.Use(auth())

			admin.POST("/auth", c.Auth)

		}

    // 路由分组

		examples := v1.Group("/examples"){

			examples.GET("ping", c.PingExample)

			examples.GET("calc", c.CalcExample)

			examples.GET("groups/:group_id/accounts/:account_id", c.PathParamsExample)

			examples.GET("header", c.HeaderExample)

			examples.GET("securities", c.SecuritiesExample)

			examples.GET("attribute", c.AttributeExample)

		}

	}

  // 关键点设置 Swagger 路由

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

	r.Run(":8080")

}



func auth() gin.HandlerFunc {

	return func(c *gin.Context) {

		if len(c.GetHeader("Authorization")) == 0 {

			httputil.NewError(c, http.StatusUnauthorized, errors.New("Authorization is required Header"))

			c.Abort()

		}

		c.Next()

	}

}

此外，一些通用API信息可以动态设置。生成的代码包文档导出SwaggerInfo变量，我们可以使用该变量以编程方式设置标题、描述、版本、主机和基本路径。

package main



import (

	"github.com/gin-gonic/gin"

	"github.com/swaggo/files"

	"github.com/swaggo/gin-swagger"



	"./docs" // docs is generated by Swag CLI, you have to import it.

)



// @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

func main() {

	// 以编程方式设置swagger信息

	docs.SwaggerInfo.Title = "Swagger Example API"

	docs.SwaggerInfo.Description = "This is a sample server Petstore server."

	docs.SwaggerInfo.Version = "1.0"

	docs.SwaggerInfo.Host = "petstore.swagger.io"

	docs.SwaggerInfo.BasePath = "/v2"

	docs.SwaggerInfo.Schemes = []string{"http", "https"}



	r := gin.New()



	// use ginSwagger middleware to serve the API docs

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



	r.Run()

}

2. 在控制器（路由处理函数）代码中使用Swagger注释来定义API文档, 此处只是展示两种情况GET或者POST请求, 有兴趣的朋友请自行查看文档。

// 以下是一个使用Swagger注释的示例：

// GET 请求示例



//	@Summary		get request example

//	@Description	get request example

//	@Tags			example

//	@Accept			json

//	@Produce		plain

//	@Param			val1	query		int		true	"used for calc"

//	@Param			enumstring	query		string	false	"string enums"		Enums(A, B, C)

//	@Param			enumint		query		int		false	"int enums"			Enums(1, 2, 3)

//	@Param			enumnumber	query		number	false	"int enums"			Enums(1.1, 1.2, 1.3)

//	@Param			string		query		string	false	"string valid"		minlength(5)	maxlength(10)

//	@Param			int			query		int		false	"int valid"			minimum(1)		maximum(10)

//  @Param			default		query		string	false	"string default"	default(A)

//  @Param   example     query     string     false  "string example"     example(string)

//  @Param   collection  query     []string   false  "string collection"  collectionFormat(multi)

//  @Param   extensions  query     []string   false  "string collection"  extensions(x-example=test,x-nullable)

//	@Param			group_id	path		int		true	"Group ID"

//	@Param			group_id	path		int		true	"Group ID"

//	@Param			Authorization	header		string	true	"Authentication header"

//	@Success		200			{string}	string	"answer"

//	@Failure		400			{string}	string	"ok"

//	@Failure		404			{string}	string	"ok"

//	@Failure		500			{string}	string	"ok"

//	@Router			/examples/groups/{group_id}/accounts/{account_id}  [get]

func (c *Controller) AttributeExample(ctx *gin.Context) {

  // URL路由参数 /{group_id}

  groupID, err := strconv.Atoi(ctx.Param("group_id"))

	if err != nil {

		httputil.NewError(ctx, http.StatusBadRequest, err)

		return

	}

	accountID, err := strconv.Atoi(ctx.Param("account_id"))

	if err != nil {

		httputil.NewError(ctx, http.StatusBadRequest, err)

		return

	}



  // Header 参数

  auth := ctx.GetHeader("Authorization")



  // URL请求参数 ? 

	ctx.String(http.StatusOK, fmt.Sprintf("enumstring=%s enumint=%s enumnumber=%s string=%s int=%s default=%s group_id=%d account_id=%d Authorization=%s",

		ctx.Query("enumstring"),

		ctx.Query("enumint"),

		ctx.Query("enumnumber"),

		ctx.Query("string"),

		ctx.Query("int"),

		ctx.Query("default"),

    groupID, 

    accountID,

    auth,

	))

}



// POST 请求示例引入接口安全校验机制

// models/model.go

package model

type Account struct {

  id     string  `form:"id" json:"id" binding:"required" example:"100001"`

	User   string  `form:"user" json:"user" binding:"required" example:"weiyigeek.top"`

	Addr   string  `form:"addr" json:"addr" example:"重庆市南岸区学府大道"`

  Hobby  []string `form:"hobby" json:"hobby" example:"计算机,烹饪,运动"`

  age    int `form:"age" json:"age" example:"25"`

} 



//	@Summary		post request example

//	@Description	post request example

//	@Tags			example

//	@Accept			json

//	@Produce		plain

//	@Param			message	body		model.Account	true	"Account Info"

//	@Success		200		{string}	string			"success"

//	@Failure		500		{string}	string			"fail"

//	@Security		ApiKeyAuth

//	@Security		OAuth2Implicit[admin, write]

//	@Router			/examples/post [post]

func (c *Controller) PostExample(ctx *gin.Context) {

  ctx.JSON(http.StatusOK, gin.H {

    "post": "ping",

  })

}

3. 使用 swag init 命令生成 Swaager UI 所需的 swagger.json 与 swagger.yaml .

# Powershell

> &"$env:GOPATH/bin/swag" init -g .\main.go

  2023/06/13 10:40:11 Generate swagger docs....

  2023/06/13 10:40:11 Generate general API Info, search dir:./

  .....

  2023/06/13 10:40:11 create docs.go at docs/docs.go

  2023/06/13 10:40:11 create swagger.json at docs/swagger.json

  2023/06/13 10:40:11 create swagger.yaml at docs/swagger.yaml

4. 执行"go run ./main.go"命令运行此Go gin项目，并使用浏览器浏览到 http://localhost:8080/swagger/index.html 站点, 您将看到Swagger 2.0 Api文档

示例代码: https://github.com/swaggo/swag/tree/master/example/celler

4. swag 项目声明性注释格式

1) 通用声明注释

2) 接口操作注释

3) 接口安全认证注释

支持的 Mime 类型 / 参数（Param） 类型 / 数据（Data）类型

温馨提示: swag接受所有格式正确的MIME类型，即match \*/\*，除此之外swag还接受一些MIME类型的别名，如下所示：

最新项目参考地址，由于时间推移（2023年6月13日 16:14:45）建议大家访问查看最新注释声明:

https://github.com/swaggo/swag/blob/master/README.md#declarative-comments-format

5. 实践内部Go-Gin项目接入Swagger

描述: 此处是作者正在开发的一个内部项目，此处我为其添加上了swagger接口文档，方便后续内部同事调用。

• Step 1.Go-Gin项目 main.go 文件示例, 即 Swagger 通用注释

package main



// @title devopsapi

// @version v1.1

// @description 安全运维中心API接口

// @termsOfService https://weiyigeek.top/terms



// @contact.name 开发者【WeiyiGeek】

// @contact.url http://weiyigeek.top/support

// @contact.email master@weiyigeek.top



// @externalDocs.description  DevOpsApi 外部文档的描述

// @externalDocs.url          https://swagger.io/resources/open-api/



// @license.name Apache 2.0

// @license.url http://www.apache.org/licenses/LICENSE-2.0.html



// @host      127.0.0.1:8080

// @BasePath  /api/v1



// @schemes http https



// @securityDefinitions.basic	BasicAuth

// $ echo -n weiyigeek:123456 | base64

// d2VpeWlnZWVrOjEyMzQ1Ng==



//	@securityDefinitions.apikey	API鉴权

//	@in							header

//	@name						Authorization

//	@description				Description for what is this security definition being used

func main() {

	// 指定 gin 运行模式

	gin.SetMode(global.App.Mode)



	// 返回一个新的空白Engine实例

	r := gin.New()



	// 设置日志中间件

	r.Use(middleware.Logger())



	// 加载自定义路由

	router.Load(r)



	// 使用 graceful 管理 Gin 服务从而优雅的停止

	srv := &graceful.Server{

		Timeout: 10 * time.Second,

		Server: &http.Server{

			// Gin运行的监听端口

			Addr: fmt.Sprintf("%s:%d", global.App.Host, global.App.Port),

			// 要调用的处理程序，http.DefaultServeMux如果为nil

			Handler: r,

			// MaxHeaderBytes控制服务器解析请求标头的键和值（包括请求行）时读取的最大字节数 (通常情况下不进行设置)

			MaxHeaderBytes: 1 << 20,

		},

	}



	// 开启一个goroutine启动服务 启动 HTTP Server

	go func() {

		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {

			log.Fatalf("listen: %s\n", err)

		}

	}()



	// 在一个新的goroutine中调用给定的函数

	// 等待中断信号

	quit := make(chan os.Signal)

	// kill 默认会发送 syscall.SIGTERM 信号

	// kill -2 发送 syscall.SIGINT 信号，我们常用的Ctrl+C就是触发系统SIGINT信号

	// kill -9 发送 syscall.SIGKILL 信号，但是不能被捕获，所以不需要添加它

	// signal.Notify把收到的 syscall.SIGINT或syscall.SIGTERM 信号转发给quit

	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM) // 此处不会阻塞

	<-quit                                               // 阻塞在此，当接收到上述两种信号时才会往下执行

	log.Println("Shutdown Server ...")



	// 创建一个 5 秒的超时上下文

	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)

	defer cancel()



	// 关闭 HTTP Server

	// 	// 5秒内优雅关闭服务（将未处理完的请求处理完再关闭服务），超过5秒就超时退出

	if err := srv.Shutdown(ctx); err != nil {

		log.Fatal("Server Shutdown:", err)

	}

	log.Println("Server exiting")

}

Step 2.Go-Gin项目routers\router.go文件示例。

package routers



// router 目录负责路由相关内容，如定义路由及路由处理函数，路由加载的中间件等



import (

	"devopsapi/docs"

	"devopsapi/handler/app"

	"devopsapi/handler/webhook"

	send "devopsapi/pkg/common"



	"github.com/gin-gonic/gin"

	swaggerfiles "github.com/swaggo/files"

	ginSwagger "github.com/swaggo/gin-swagger"

)



// Load 中负责加载中间件 middlewares、路由 routes 和 handlers

func Load(r *gin.Engine, mw ...gin.HandlerFunc) *gin.Engine {



	// 请求异常处理

	r.NoRoute(send.HandleNotFound)

	r.NoMethod(send.HandleNotFound)



	// 前端项目静态资源

	r.StaticFile("/", "./static/dist/index.html")

	r.StaticFile("/favicon.ico", "./static/dist/favicon.ico")

	r.Static("/assets", "./static/dist/assets")



	// 单路由

	// r.GET("/app/version", app.Version)



	// Swagger 对象方式设置基础路径

	docs.SwaggerInfo.BasePath = "/api/v1"



	// 路由组

	_app := r.Group("/app")

	{

		_app.GET("/version", app.Version)

		_app.POST("/restart", app.Restart)

	}



	_v1 := r.Group("/api/v1")

	{

		_v1.POST("/webhook/qywx", webhook.QYWXSendMsg)

		_v1.POST("/webhook/dingtalk", webhook.DingtalkSendMsg)

		_v1.POST("/webhook/email", webhook.EmailSendMsg)

	}



	// ginSwagger 路由处理

	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))

	// 加载中间件

	r.Use(mw...)

	return r

}

Step 3.Go-Gin项目handler\webhook\qywx.go文件示例，添加了swagger的接口注释。

package webhook



import (

	send "devopsapi/pkg/common"

	"devopsapi/pkg/global"

	"devopsapi/pkg/util/webhooks"

	"fmt"

	"log"



	"github.com/gin-gonic/gin"

)



type qywxCommonType struct {

	Key  string `form:"key" json:"key" binding:"required"`

	Type string `form:"type" json:"type" binding:"required"`

	Msg  string `form:"msg" json:"msg" binding:"required"`

	User string `form:"user" json:"user"`

}



type qywxCustomMarkdownType struct {

	Key     string `form:"key" json:"key" binding:"required"`

	Type    string `form:"type" json:"type" binding:"required"`

	Title   string `form:"title" json:"title" binding:"required"`

	Project string `form:"project" json:"project" binding:"required"`

	Msg     string `form:"msg" json:"msg" binding:"required"`

	UrlText string `form:"urltext" json:"urltext"`

	UrlAddr string `form:"urladdr" json:"urladdr"`

	User    string `form:"user" json:"user"`

}



type qywxImageType struct {

	Key     string `form:"key" json:"key" binding:"required"`

	Type    string `form:"type" json:"type" binding:"required"`

	ImgData string `form:"imgdata" json:"imgdata" binding:"required"`

	ImgMd5  string `form:"imgmd5" json:"imgmd5" binding:"required"`

}



// 使用企业微信机器人发送信息 （GET）示例 Swagger



// @Summary 企业微信机器人信息发送

// @Description 使用企业微信机器人发送多种类型信息到对应群聊

// @Tags 消息通知

// @Accept application/json

// @Produce application/json

// @Param key query string true "鉴权Key"

// @Param type query string true "消息类型"

// @Param msg query string true "发送的消息"

// @Param user query string false "接收者手机或名称"

// @Param title query string false "消息标题"

// @Param project query string false "消息主题"

// @Param urltext query string false "消息连接文本"

// @Param urladdr query string false "消息连接"

// @Param imgdata query string false "图片base64数据"

// @Param imgmd5 query string false "图片MD5值"

// @Success 200 {string} QYWXSendMsg

// @Router /webhook/qywx [POST]

func QYWXSendMsg(c *gin.Context) {

	qywx_key := c.Query("key")

	qywx_url := fmt.Sprintf("%s%s", global.WebHook.Qywechat, qywx_key)

	msg_type := c.Query("type")

	....... 此处略过n行代码

}

Step 4.Go-Gin项目handler\webhook\email.go文件示例，添加了swagger的接口注释。

type emailType struct {

	Type     string   `form:"type" json:"type" binding:"required" example:"text|html|file|tpl"`

	To       []string `form:"to" json:"to" binding:"required" example:"master@weiyigeek.top"`

	Cc       []string `form:"cc" json:"cc" example:"master@weiyigeek.top"`

	Subject  string   `form:"subject" json:"subject" binding:"required" example:"邮件主题"`

	Body     string   `form:"body" json:"body"  binding:"required" example:"邮件内容"`

	File     string   `form:"file" json:"file" example:"/app/storage/public/weiyigeek.jpg"`

	Filename string   `form:"filename" json:"filename" example:"weiyigeek-作者照片"`

	Template string   `form:"tpl" json:"tpl"  example:"TemplateVerifiy"`

}



// 使用企业邮箱发送邮件信息 （POST） 示例 Swagger



// @Summary 企业邮箱信息发送

// @Description 使用企业邮箱发送多种类型的邮件信息

// @Tags 消息通知

// @Accept json

// @Produce json

// @Param type query string true "发送类型"

// @Param body body emailType true "请求body"

// @Success 200 {string} EmailSendMsg

// @Security		BasicAuth

// @Security		API鉴权

// @Router /webhook/email [POST]

func EmailSendMsg(c *gin.Context) {

	sendType := c.Query("type")

  ....... 此处略过n行代码

}

Step 5.命令行进入到Go-Gin项目devopsapi目录中，执行 swag init 生成 swagger-ui 所需文件, 生成完毕后便可运行该项目。

# PowerShell

cd devopsapi # 进入项目根路径

&"$env:GOPATH/bin/swag" init -g ./main.go -o ./docs  # 初始化文档

  # 2023/06/13 17:55:52 Generate swagger docs....

  # 2023/06/13 17:55:52 Generate general API Info, search dir:./

  # 2023/06/13 17:55:52 Generating webhook.emailType

  # 2023/06/13 17:55:52 create docs.go at docs/docs.go

  # 2023/06/13 17:55:52 create swagger.json at docs/swagger.json

  # 2023/06/13 17:55:52 create swagger.yaml at docs/swagger.yaml



# 运行此app应用

PS D:\Study\Project\Go\devopsapi> go run .\main.go

Step 6.运行后访问 http://127.0.0.1:8080/swagger/index.html 查看swagger接口文档，效果如下所示，

除此之外，我们还可以使用swagger-UI进行在线模拟请求我们开发的接口，是不是非常方便呀!

本文至此完毕，更多技术文章，尽情等待下篇好文！

原文地址: https://blog.weiyigeek.top/2023/6-5-746.html

本文章转载微信公众号@全栈工程师修炼指南