当前位置：首页 > news >正文

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

news 来源：原创 2025/5/21 22:34:25

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

环境准备

在这里插入图片描述

下面是已存在项目的文件结构：
在这里插入图片描述
后面我们在此基础上增加swagger生成API文档功能。

安装依赖

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

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 mainimport (_ "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身份验证实现添加了下面的代码。

// @securityDefinitions.apiKey JWT
// @in header
// @name token

API文档注释

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

package handlerimport ("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模型代码：

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

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

在这里插入图片描述
我们看到Item数据的必填属性与model定义一致。

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

// @securityDefinitions.apiKey token
// @in header
// @name Authorization
// @Security JWT

再次运行，可以看到右侧锁标志。
在这里插入图片描述

总结

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

环境准备

安装依赖

生成文档

API文档注释

总结

相关文章：