后端技术

基于gin的golang web开发：集成swagger

在前后端分离的项目维护一份完整且及时更新的api文档会极大的提高我们的工作效率，传统项目中接口文档都是由后端开发手写的，这种文档很难保证及时性，久而久之便失去了参考意义。swagger给我们提供了一种新的维护文档的方式，在gin中只需要编写一些注释即可生成一份可交互的接口文档。

1
2
3
go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/files

引入这些包之后就可以通过给方法写注释的方式生成接口文档。github.com/swaggo/swag/cmd/swag中包含一个用于生成接口文档的命令行工具swag，github.com/swaggo/gin-swagger是一个gin中间件，github.com/swaggo/files中包含了swagger UI的一些如css、js等必要的文件。

与gin集成

我们需要在代码中引入必要的包，并且在main方法上增加两个必填的通用API注释title和version，这两个注释分别表示应用程序的名称和应用程序API的版本，这些内容会显示在swagger ui中。代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
package main

import (
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
	_ "proj/docs"
)

// @title 用户中心API
// @version 1.0
func main() {
	engine := gin.Default()

	url := ginSwagger.URL("/swagger/doc.json")
	engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

	_ = engine.Run(":8081")
}

我们在代码中定义doc.json的文件地址为/swagger/doc.json，swagger ui会解析这个地址渲染页面。紧接着定义路由规则/swagger/*any全部经由ginSwagger.WrapHandler中间件处理。

在包含main.go文件的项目根目录运行swag init。这将会解析注释并生成docs/docs.go和swagger所需的文件，最后引用docs_ "proj/docs"，proj是项目名。

现在访问http://localhost:8081/swagger/index.html就会看到熟悉的swagger ui页面。

编写接口注释信息

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
type SysRole struct {
	Id          int64       `json:"id"`
	Name        null.String `json:"name" swaggertype:"string"` // 角色名
	Description null.String `json:"description" swaggertype:"string"`
	Available   null.Int    `json:"available" swaggertype:"integer"`
	CreateTime  null.Time   `json:"create_time" db:"create_time" swaggertype:"string"` // 添加时间
	UpdateTime  null.Time   `json:"update_time" db:"update_time" swaggertype:"string"` // 更新时间
}

// 角色列表
// @Summary 角色列表
// @Description 角色列表
// @Tags 角色
// @Success 200 {array} SysRole
// @Router /roles [get]
func RoleList(c *gin.Context) {
	list := sysRole.GetAllRole()

	c.JSON(http.StatusOK, list)
}

我们分别在model和handler方法上增加一些必要的信息。

Name字段在SysRole结构体中的类型为null.String，但是swag init生成文档时因为不能自动解析null包产生如下错误信息：

1
ParseComment error in file xxxxxxx.go :cannot find package path of type: null.String

一种解决方案是命令改为执行swag init --parseDependency解析外部依赖，这个命令需要解析大量的外部依赖运行时间很长，而且似乎也并不能解决所有问题。更推荐使用以上代码中的swaggertype标签来解决问题。swaggertype标签指定swagger中使用的类型，如int类型字段设置标签为swaggertype:"integer"。

handler方法上增加注释描述当前接口的信息。@Summary和@Description设置接口的概要和描述信息。@Tags设置接口的分组，例如有接口 /roles 和 /roles/[:id] 都返回角色相关的信息，那么这两个handler的注释可以统一设置为 @Tags 角色。@Success设置接口成功返回的内容，这里设置为SysRole数组，当然还有@Failure设置接口失败的返回结果。@Router设置接口的路由。