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

已于 2023-06-14 09:14:08 修改
阅读量2.3k 收藏 5
点赞数 1
分类专栏： 后端开发 文章标签： golang gin java 开发语言 后端
于 2023-06-13 18:21:41 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/u013072756/article/details/131199154
版权

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

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

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

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

“  花开堪折直须折，莫待无花空折枝。 ”

作者主页：[ 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

欢迎关注 【全栈工程师修炼指南】(＾Ｕ＾)ノ~ＹＯ

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

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

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

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

点个【赞 + 在看】吧！

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

全栈工程师修炼指南
关注
专栏目录
Golang使用swagger生成api接口文档
geek99_guo的博客
03-19 288
现在大部分应用都是前后端分离的项目，那么，前端和后端交互只有通过api接口文档来实现。swagger可以根据注释来生成api接口文档。
gin 生成api文档_Go gin框架 使用swagger生成API文档
weixin_39623411的博客
12-22 668
swaggos 是一个golang版本的swagger文档生成器，提供了native code包装器，并且支持主流的web框架包裹器下载安装 swag$ go get -u github.com/swaggo/swag/cmd/swag在Go项目根文件夹中运行Swag在main.go所在目录执行 swag init, -g 参数是输出详细信息执行后，会生成docs/doc.go以及docs/swa...
Gin-Swagger：一个用于Gin框架的Swagger集成工具
最新发布
gitblog_00187的博客
08-08 303
Gin-Swagger：一个用于Gin框架的Swagger集成工具 gin-swaggergin middleware to automatically generate RESTful API documentation with Swagger 2.0.项目地址:https://gitcode.com/gh_mirrors/gi/gin-swagger 本文将指导您了解如何使用gin-swa...
Gin-swagger
戴某某
01-07 210
Gin-swagger的使用
Go 语言：使用 GinSwagger 库生成 API 文档
m0_62153576的博客
10-14 481
在docs文件夹中的docs.go文件中，你可以自定义 Swagger 文档的信息，包括标题、版本、描述等。
使用 Gin-Docs 自动生成 API 文档
Braiden的博客
05-15 414
还有一些其他的第三方库和工具可以帮助你生成 API 文档，但它们的普及程度可能不如 Swagger。你可以编写一个自定义的工具，使用 Go 的反射功能来遍历你的 Gin 路由和处理器函数，并生成文档。Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。如果自动生成的文档不满足你的需求，或者你的 API 非常简单，那么手动编写文档可能是一个更快、更直接的方法。或其他类似的库来为你的 Gin API 生成 Swagger 文档。
gin-swagger:使用 Swagger 2.0 自动生成 RESTful API 文档的 gin 中间件
07-24
gin 中间件使用 Swagger 2.0 自动生成 RESTful API 文档。 用法 开始使用它 向您的 API 源代码添加注释，。 使用以下命令下载 for Go： $ go get -u github.com/swaggo/swag/cmd/swag 在包含main.go文件的 Go 项目...
gin + swagger 生成api接口文档及错误处理
qq_44662924的博客
12-20 1223
gin swagger
gin集成Swagger-UI
weixin_44840774的博客
03-27 762
gin 中间件使用 Swagger 2.0 自动生成 RESTFUL API 文档。 1. 安装Swagger 使用以下命令下载Swag for Go： go get -u github.com/swaggo/swag/cmd/swag 在 Go 项目根路径运行Swag ， Swag将解析注释并生成所需的文件和文件夹。 swag init 生成目录如下： . ├── docs │ ├── docs.go │ ├── swagger.json │ └── swagger.yaml ├── g
Golang: Gin Swagger 配置
Allan_shore_ma的博客
03-04 886
Gin Swagger 配置     swagger是一套基于OpenAPI规范构建的开源工具，使用RestApi。swagger-ui 呈现出来的是一份可交互式的API文档，可以直接在文档页面尝试API的调用。     gin-swagger 是基于注释生成 API 文档，项目地址:https://github.com/swaggo/swag。
mswagger:使用golang生成swagger 2.0 json文件
05-17
也许您可以尝试 mswagger 基于存储库。 去做 支持解析供应商文件夹。 生成swagger 2.0 json文件。 使用swagger-ui修复某些字段类型的映射。 用法 在main.go中发表评论 // @Version 1.0.0 // @Title Backend API // @Description API usually works as expected. But sometimes its not true. // @BasePath / // @Schemes http,https // @ContactName Abcd // @ContactEmail abce@email.com // @ContactURL http://someurl.oxox // @TermsOfServiceUrl http://someurl.oxox // @Licens
gin使用swagger
weixin_30746129的博客
06-02 572
swagger可以通过代码实时维护后台API接口，这样可以减小前端开放人员和后端开发人员因为API变更带来的矛盾。 初级入门： https://razeencheng.com/post/go-swagger.html 高级提升： https://github.com/swaggo
gin-swagger
xiaoxiaoyu85的专栏
04-25 294
// @title Swagger Example API // @version 1.0 // @description This is a sample server Petstore server. // @termsOfService http://swagger.io/terms/ // @contact.name API Support // @contact.url http://www.swagger.io/support // @contact.email support@swagge.
Gin 生成 Swagger 接口文档
Dablelv 的博客专栏。
02-07 1444
采用工具生成，不同的工具生成的接口文档风格不一，增加阅读者的理解成本。使用 Swagger 就是把接口相关信息存储在它定义的描述文件里面（yaml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。生成 API 描述文件后，便可通过 Swagger 为我们提供的库，将 API 描述文件集成到服务中，通过接口的形式提供在线文档。可以在请求 Body 对应的 struct 中添加注释，在接口的请求参数中添加说明，引用自具体的 struct。
Gin框架中配置Swagger（完整流程版）
无言.
05-10 4594
Gin框架中配置Swagger。Swagger是一个API文档工具，可以用于自动生成、描述、调试和可视化RESTful API文档。其通过标准化API的描述格式和工具链，帮助开发者快速创建和部署API。
golang restful 框架之 go-swagger
hatlonely的专栏
02-09 7137
restful 是这些年的高频词汇了，各大互联网公司也都纷纷推出了自己的 restful api，其实 restful 和 thrift，grpc 类似，就是一种协议，但是这种协议有点特殊的就是使用 http 接口，返回的对象一般是 json 格式，这样有个好处，就是可以供前端的 js 直接调用，使用非常方便，但 http 本身并不是一个高效的协议，后端的内部通信还是使用 grpc 或者 thri...
简明教程gin-swagger
ywtech的博客
05-26 922
gin-swagger gin middleware to automatically generate RESTful API documentation with Swagger 2.0. Usage Start using it Add comments to your API source code, See Declarative Comments Format. Download Swag for Go by using: go get -u github.com/swaggo/swag/c
微服务架构（从无到有）二.客户端代码完善 2） gin+swagger 自动生成API接口文档
wangzhe
01-06 247
##使用 swagger 日志服务 go get -u github.com/swaggo/swag/cmd/swag swag init // 要和main.go处于同一级目录 编辑 initialize/router.go 引入包 swaggerFiles "github.com/swaggo/files" ginSwagger "github.com/swaggo/gin-swagger" 在Routers := gin.Default()下面增加 r.GET("/swagger/*a
gin 集成swagger
gxzhaha的博客
03-10 308
安装 swag $ go get -u github.com/swaggo/swag/cmd/swag 验证是否安装成功 $ swag -v swag version v1.1.1 安装 gin-swagger $ go get -u github.com/swaggo/gin-swagger $ go get -u github.com/swaggo/gin-swagger/swaggerFiles 编写API注释 以官网文档为范例 // @Summary Add a new p
gin-swagger:使用 swagger 2.0 自动生成 restful api 文档的 gin 中间件
09-02
总之，gin-swagger是一个非常实用的工具，它使得开发者在使用gin框架开发RESTful API时，能够方便地自动生成API文档，提高开发效率。同时，通过API文档的可视化呈现，也能够帮助开发者更好地理解和使用API。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

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

打赏作者

全栈工程师修炼指南

原创不易，赞赏鼓励!

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

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

打赏作者

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

抵扣说明：

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

余额充值