Golang Gin系列-9:Gin 集成Swagger生成文档

文档一直是一项乏味的工作(以我个人的拙见),但也是编码过程中最重要的任务之一。在本文中,我们将学习如何将Swagger规范与Gin框架集成。我们将实现JWT认证,请求体作为表单数据和JSON。这里唯一的先决条件是Gin服务器。您可以在这里参考github上现有的api。

环境准备

下面是已存在项目的文件结构:

后面我们在此基础上增加swagger生成API文档功能。

安装依赖

swag命令把Go 源码中的注释转换为Swagger文档。

shell 复制代码
go get -u github.com/swaggo/swag/cmd/swag

另外还需要安装两个依赖:

复制代码
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

gin-swagger使用gin中间件在Swagger 2.0中自动生成RESTful API文档;文件生成swagger UI嵌入文件。

生成文档

在项目的根文件夹中运行swag init 命令,根目录包含main.go文件。这将解析你的注释并生成所需的文件(docs文件夹和docs/docs.go)。

下面构建项目并启动web服务,使用下面命令:

复制代码
$ go build 

它将构建并创建可执行文件。然后运行可执行文件。现在导航到http://localhost:8081/swagger/index.html,看看它是否正常工作。

好像有点不对劲。让我们一起努力吧。

导入生成的docs/docs,在main.go的导入部门初始化特定配置。此外,我们将在main.go中添加通用API注释。

复制代码
package main

import (
	_ "go-api/docs"
	"go-api/handler"

	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

//	@title						Demo APIs
//	@version					1.0
//	@description				Testing Swagger APIs.
//	@termsOfService				http://swagger.io/terms/
//	@contact.name				API Support
//	@contact.url				http://www.swagger.io/support
//	@contact.email				support@swagger.io
//	@securityDefinitions.apiKey	JWT
//	@in							header
//	@name						token
//	@license.name				Apache 2.0
//	@license.url				http://www.apache.org/licenses/LICENSE-2.0.html
//	@host						localhost:8081
//	@BasePath					/api/v1
//	@schemes					http
func main() {
	r := gin.Default()
	// url := ginSwagger.URL("http://localhost:8080/swagger/doc.json")
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

	r.Run(":8080")
}
  • 👉请注意注释之间的间距,因为这是swagger规范。
  • 👉此外,每当我们添加或更新update注释时,需要再次运行"swag init"命令来更新文档。好了,现在让我们构建并运行它,并检查我们是否取得了进展。

它起作用了😃。

另外,请注意,我们已经为UI中的JWT身份验证实现添加了下面的代码。

python 复制代码
// @securityDefinitions.apiKey JWT
// @in header
// @name token

API文档注释

现在,让我们将文档注释添加到API端点。

go 复制代码
package handler

import (
	"github.com/gin-gonic/gin"
)

// @Summary 获取item
// @Description 根据ID查询item信息
// @Accept  json
// @Produce  json
// @Param id path int true "ID"
// @Success 200 {object} map[string]interface{}
// @Router /items/{id} [get]
func GetItem(c *gin.Context) {
	// Implement the logic to get an item
}

// @Summary 示例 API
// @Description 这是一个示例 API 的描述
// @Accept  mpfd
// @Produce  json
// @Param item formData model.Item true "item data"
// @Success 200 {object} map[string]interface{}
// @Router /items/create [post]
func CreateItem(c *gin.Context) {
	// Implement the logic to create a new item
}

我们使用@Accept作为mpfd (multipart/form-data),它生成JSON并使用Item 模型作为DTO。@Tags有助于将api组织到一个组中。你也可以使用swag fmt来格式化注释。

Item模型代码:

go 复制代码
package model

type Item struct {
	ID    int     `json:"id"`
	Name  string  `json:"name"  binding:"required"`
	Price float64 `json:"price"  binding:"required"`
}

再次运行 swag init 命令 ,然后构建项目并运行:

我们看到Item数据的必填属性与model定义一致。

最后一步,给Post请求增加JWT 认证。我们在请求端点文档中增加下面代码:

python 复制代码
// @securityDefinitions.apiKey token
// @in header
// @name Authorization
// @Security JWT

再次 运行,可以看到右侧锁标志。

总结

本文介绍了Gin如何集成Swagger,包括安装依赖,增加API接口注释文档,以及如何配置表单数据参数和JWT认证等。Gin,愈学习愈快乐, Go!

相关推荐
月忆3645 分钟前
Etcd原理基础学习
分布式·golang
五岁小孩2 小时前
Golang 性能分析神器 pprof 详解与实践(图文教程)
性能优化·golang·pprof
江湖有缘7 小时前
【Docker项目实战】在Docker环境下部署go-file文件分享工具
docker·容器·golang
自学也学好编程16 小时前
【学习路线】Go语言云原生开发之路:从简洁语法到微服务架构
学习·golang
Python涛哥19 小时前
go语言基础教程:【1】基础语法:变量
开发语言·后端·golang
whhhhhhhhhw1 天前
安装及配置Go语言开发环境与VSCode集成指南
开发语言·学习·golang
IT之家1 天前
swagger文档生成html静态文档
swagger·openapi·离线文档
Code季风1 天前
Gin Web 服务与 Consul 集成实战:服务注册到发现全流程(下)
微服务·go·gin
神器阿龙1 天前
XORM完全指南:Go语言数据库操作从入门到进阶
开发语言·数据库·golang
一念&2 天前
go和c#谁比较节省内存
golang·c#