[TOC]

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 ] ，请注意对应系统版本 .

weiyigeek.top-二进制Go-Swagger下载图

• 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) 通用声明注释

annotation	description	example
title	Required. The title of the application.	// @title Swagger Example API
version	Required. Provides the version of the application API.	// @version 1.0
description	A short description of the application.	// @description This is a sample server celler server.
tag.name	Name of a tag.	// @tag.name This is the name of the tag
tag.description	Description of the tag	// @tag.description Cool Description
tag.docs.url	Url of the external Documentation of the tag	// @tag.docs.url https://example.com
tag.docs.description	Description of the external Documentation of the tag	// @tag.docs.description Best example documentation
termsOfService	The Terms of Service for the API.	// @termsOfService http://swagger.io/terms/
contact.name	The contact information for the exposed API.	// @contact.name API Support
contact.url	The URL pointing to the contact information. MUST be in the format of a URL.	// @contact.url http://www.swagger.io/support
contact.email	The email address of the contact person/organization. MUST be in the format of an email address.	// @contact.email support@swagger.io
license.name	Required. The license name used for the API.	// @license.name Apache 2.0
license.url	A URL to the license used for the API. MUST be in the format of a URL.	// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
host	The host (name or ip) serving the API.	// @host localhost:8080
BasePath	The base path on which the API is served.	// @BasePath /api/v1
accept	A list of MIME types the APIs can consume. Note that Accept only affects operations with a request body, such as POST, PUT and PATCH. Value MUST be as described under Mime Types.	// @accept json
produce	A list of MIME types the APIs can produce. Value MUST be as described under Mime Types.	// @produce json
query.collection.format	The default collection(array) param format in query,enums:csv,multi,pipes,tsv,ssv. If not set, csv is the default.	// @query.collection.format multi
schemes	The transfer protocol for the operation that separated by spaces.	// @schemes http https
externalDocs.description	Description of the external document.	// @externalDocs.description OpenAPI
externalDocs.url	URL of the external document.	// @externalDocs.url https://swagger.io/resources/open-api/
x-name	The extension key, must be start by x- and take only json value	// @x-example-key {“key”: “value”}

2) 接口操作注释

annotation	description
description	A verbose explanation of the operation behavior.
description.markdown	A short description of the application. The description will be read from a file. E.g. `@description.markdown detailswill loaddetails.md`
id	A unique string used to identify the operation. Must be unique among all API operations.
tags	A list of tags to each API operation that separated by commas.
summary	A short summary of what the operation does.
accept	A list of MIME types the APIs can consume. Note that Accept only affects operations with a request body, such as POST, PUT and PATCH. Value MUST be as described under Mime Types.
produce	A list of MIME types the APIs can produce. Value MUST be as described under Mime Types.
param	Parameters that separated by spaces. param name,param type,data type,is mandatory?,comment attribute(optional)
security	Security to each API operation.
success	Success response that separated by spaces. return code or default,{param type},data type,comment
failure	Failure response that separated by spaces. return code or default,{param type},data type,comment
response	As same as success and failure
header	Header in response that separated by spaces. return code,{param type},data type,comment
router	Path definition that separated by spaces. path,[httpMethod]
x-name	The extension key, must be start by x- and take only json value.
x-codeSample	Optional Markdown usage. take file as parameter. This will then search for a file named like the summary in the given folder.
deprecated	Mark endpoint as deprecated.

3) 接口安全认证注释

annotation	description	parameters	example
securitydefinitions.basic	Basic auth.		// @securityDefinitions.basic BasicAuth
securitydefinitions.apikey	API key auth.	in, name, description	// @securityDefinitions.apikey ApiKeyAuth
securitydefinitions.oauth2.application	OAuth2 application auth.	tokenUrl, scope, description	// @securitydefinitions.oauth2.application OAuth2Application
securitydefinitions.oauth2.implicit	OAuth2 implicit auth.	authorizationUrl, scope, description	// @securitydefinitions.oauth2.implicit OAuth2Implicit
securitydefinitions.oauth2.password	OAuth2 password auth.	tokenUrl, scope, description	// @securitydefinitions.oauth2.password OAuth2Password
securitydefinitions.oauth2.accessCode	OAuth2 access code auth.	tokenUrl, authorizationUrl, scope, description	// @securitydefinitions.oauth2.accessCode OAuth2AccessCode

parameters annotation	example
in	// @in header
name	// @name Authorization
tokenUrl	// @tokenUrl https://example.com/oauth/token
authorizationurl	// @authorizationurl https://example.com/oauth/authorize
scope.hoge	// @scope.write Grants write access
description	// @description OAuth protects our entity endpoints

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

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

weiyigeek.top-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

weiyigeek.top-devopsapi项目运行图

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

weiyigeek.top-swagger-UI图

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

weiyigeek.top-swagger-UI模拟请求图