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

欢迎关注「全栈工程师修炼指南」公众号

点击 👇 下方卡片 即可关注我哟!

设为星标⭐每天带你 基础入门 到 进阶实践 再到 放弃学习

专注 企业运维实践、网络安全、系统运维、应用开发、物联网实战、全栈文章 等知识分享

  花开堪折直须折,莫待无花空折枝 


作者主页:[ https://www.weiyigeek.top ]  

博客:[ https://blog.weiyigeek.top ]

作者<开发安全运维>学习交流群,回复【学习交流群】即可加入

原文链接:

Golang | Web开发之Gin使用swag生成项目的Swagger-API接口文档Swagger提供了最强大和最容易使用的工具,以充分利用OpenAPI规范。go-swagger是一个主要生成或分析源代码的工具,我们可以使用go-swagger工具为Gin项目使用Swagger 2.0自动生成RESTful API文档。https://mp.weixin.qq.com/s/vcEv4DoA7g40AFyBuoXeRA


文章目录:

4d49427280eb54ccd80c5db44a6406d9.png

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

94d23c6ac4c9f5ce794ab46f5b77d979.png

  • 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

c9834c8f2cb1ce1d82ef73e53d239e56.png

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

1) 通用声明注释

annotationdescriptionexample
titleRequired. The title of the application.// @title Swagger Example API
versionRequired. Provides the version of the application API.// @version 1.0
descriptionA short description of the application.// @description This is a sample server celler server.
tag.nameName of a tag.// @tag.name This is the name of the tag
tag.descriptionDescription of the tag// @tag.description Cool Description
tag.docs.urlUrl of the external Documentation of the tag// @tag.docs.url https://example.com
tag.docs.descriptionDescription of the external Documentation of the tag// @tag.docs.description Best example documentation
termsOfServiceThe Terms of Service for the API.// @termsOfService http://swagger.io/terms/
contact.nameThe contact information for the exposed API.// @contact.name API Support
contact.urlThe URL pointing to the contact information. MUST be in the format of a URL.// @contact.url http://www.swagger.io/support
contact.emailThe email address of the contact person/organization. MUST be in the format of an email address.// @contact.email support@swagger.io
license.nameRequired. The license name used for the API.// @license.name Apache 2.0
license.urlA 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
hostThe host (name or ip) serving the API.// @host localhost:8080
BasePathThe base path on which the API is served.// @BasePath /api/v1
acceptA 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
produceA list of MIME types the APIs can produce. Value MUST be as described under Mime Types.// @produce json
query.collection.formatThe default collection(array) param format in query,enums:csv,multi,pipes,tsv,ssv. If not set, csv is the default.// @query.collection.format multi
schemesThe transfer protocol for the operation that separated by spaces.// @schemes http https
externalDocs.descriptionDescription of the external document.// @externalDocs.description OpenAPI
externalDocs.urlURL of the external document.// @externalDocs.url https://swagger.io/resources/open-api/
x-nameThe extension key, must be start by x- and take only json value// @x-example-key {"key": "value"}

2) 接口操作注释

annotationdescription
descriptionA verbose explanation of the operation behavior.
description.markdownA short description of the application. The description will be read from a file. E.g. @description.markdown details will load details.md
idA unique string used to identify the operation. Must be unique among all API operations.
tagsA list of tags to each API operation that separated by commas.
summaryA short summary of what the operation does.
acceptA 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.
produceA list of MIME types the APIs can produce. Value MUST be as described under Mime Types.
paramParameters that separated by spaces. param name,param type,data type,is mandatory?,comment attribute(optional)
securitySecurity to each API operation.
successSuccess response that separated by spaces. return code or default,{param type},data type,comment
failureFailure response that separated by spaces. return code or default,{param type},data type,comment
responseAs same as success and failure
headerHeader in response that separated by spaces. return code,{param type},data type,comment
routerPath definition that separated by spaces. path,[httpMethod]
x-nameThe extension key, must be start by x- and take only json value.
x-codeSampleOptional Markdown usage. take file as parameter. This will then search for a file named like the summary in the given folder.
deprecatedMark endpoint as deprecated.

3) 接口安全认证注释

annotationdescriptionparametersexample
securitydefinitions.basicBasic auth.// @securityDefinitions.basic BasicAuth
securitydefinitions.apikeyAPI key auth.in, name, description// @securityDefinitions.apikey ApiKeyAuth
securitydefinitions.oauth2.applicationOAuth2 application auth.tokenUrl, scope, description// @securitydefinitions.oauth2.application OAuth2Application
securitydefinitions.oauth2.implicitOAuth2 implicit auth.authorizationUrl, scope, description// @securitydefinitions.oauth2.implicit OAuth2Implicit
securitydefinitions.oauth2.passwordOAuth2 password auth.tokenUrl, scope, description// @securitydefinitions.oauth2.password OAuth2Password
securitydefinitions.oauth2.accessCodeOAuth2 access code auth.tokenUrl, authorizationUrl, scope, description// @securitydefinitions.oauth2.accessCode OAuth2AccessCode
parameters annotationexample
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类型的别名,如下所示:

a86ab063b107658ac3dc8f6114087630.png

最新项目参考地址,由于时间推移(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

f5b5027c435515c32195475f9565306d.png

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

991b5e2f0a292565c96f995244525635.png

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

32ff10bf8298faa081a9f67c97902d61.png

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

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

如果此篇文章对你有帮助,请你将它分享给更多的人! 

821ee7a1fb179bb833cfe3179aa9a383.gif

f04cc165719555feec2d69f1be599065.png 学习书籍推荐 往期发布文章 d602ceed22ee2eeddc4edc716b3b7de4.png

公众号回复【0008】获取【Ubuntu22.04安装与加固脚本】

公众号回复【10001】获取【WinServer安全加固脚本】

公众号回复【10002】获取【KylinOS银河麒麟安全加固脚本】

公众号回复【0011】获取【k8S二进制安装部署教程】

公众号回复【0014】获取【Nginx学习之路汇总】

公众号回复【0015】获取【Jenkins学习之路汇总】

公众号回复【10005】获取【adb工具刷抖音赚米】

 热文推荐  

欢迎长按(扫描)二维码 取更多渠道哟!

53e197f463ecac070f3515b5e4cebe95.gif

欢迎关注 【全栈工程师修炼指南】(^U^)ノ~YO

添加作者微信【weiyigeeker 】 一起学习交流吧!

关注回复【学习交流群】即可加入【安全运维沟通交流小群

温馨提示: 由于作者水平有限,本章错漏缺点在所难免,希望读者批评指正,若有问题或建议请在文章末尾留下您宝贵的经验知识,或联系邮箱地址

master@weiyigeek.top 或 关注公众号 [全栈工程师修炼指南] 留言。

点个【赞 + 在看】吧!

点击【"阅读原文"】获取更多有趣的知识!   

  • 1
    点赞
  • 4
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

全栈工程师修炼指南

原创不易,赞赏鼓励!

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值