Golang Gin系列-9：Gin 集成Swagger生成文档
文档一直是一项乏味的工作（以我个人的拙见），但也是编码过程中最重要的任务之一。在本文中，我们将学习如何将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 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身份验证实现添加了下面的代码。
// @securityDefinitions.apiKey JWT
// @in header
// @name token
API文档注释
现在，让我们将文档注释添加到API端点。
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模型代码：
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 认证。我们在请求端点文档中增加下面代码：
// @securityDefinitions.apiKey token
// @in header
// @name Authorization
// @Security JWT
再次 运行，可以看到右侧锁标志。
总结
本文介绍了Gin如何集成Swagger，包括安装依赖，增加API接口注释文档，以及如何配置表单数据参数和JWT认证等。Gin，愈学习愈快乐， Go!