随着RESTful API的流行，Swagger已经成为了一种通用的API描述和文档格式。它可以帮助开发者描述、测试和文档化RESTful API。在本文中，我们将介绍在go中如何使用相应的库生成swagger文档。在golang中, 有两款可以生成swagger的库，一般我们选择https://github.com/swaggo/swag,还有另一款https://github.com/go-swagger/go-swagger,相对来说，使用起来swag更易用一点

安装

1

go install github.com/swaggo/swag/cmd/swag@latest

默认情况下，会安装在go path相关的目录下，该目录一般已经加入环境变量，若没有加入环境变量，我们可根据每种系统的不同，手动加入至环境变量中

检测是否安装成功：

1

swag -v

返回具体的版本号即成功:

1

swag.exe version v1.8.12

使用

路由绑定

我们使用的是gin框架，swag对gin也有集成封装, 我们可以在gin的路由绑定至对应的swagger文档

1
2
3

// swagger文档查看路径
url := ginSwagger.URL("/swagger/doc.json") // The url pointing to API definition
r.GET("swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

依赖库：

1
2

swaggerFiles "github.com/swaggo/files"
"github.com/swaggo/gin-swagger"

路由注释

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// ListUser
// @Summary 查询用户信息
// @Tags 用户
// @Description	查询用户信息
// @Produce	json
// @Param UserId header string true "当前用户id"
// @Param query query dto.ListReq true "query参数"
// @Success	200	{object} dto.ListUserResp "成功"
// @Router /user/api/v1/tnt/user/list [get]
func (u *UserService) ListUser(ctx *gin.Context){}

文档注释

在入口main.go文件增加注释

1
2
3
4
5

// @title		用户服务
// @version		1.0
// @description	用户服务API(包含用户，用户组，角色，租户，策略，授权等功能接口)
func main() {
}

引入对应的文档目录，这步很关键，他可以将模板的信息注册到swagger实例中

1
2
3

import (
    _ "userApp/docs"
)

通过命令将注释生成文档

在项目根目录执行以下命令，使用swag工具生成接口文档数据

1

swag init -g ./cmd/main.go -o ./docs

因为项目根目录不一定和main.go一个目录，所以，但执行这个命令你不能去main.go的目录执行，会报错.

错误1：所以直接使用swag init这个前提是main.go在根目录下，不在同一目录下直接执行报如下错误：

1
2

warning: failed to get package name in dir:
cannot parse source files:xxx

错误2：如果去main.go的目录执行，可以执行成功，但并不能生成对应的文档。

解决方案：https://github.com/swaggo/gin-swagger/issues/73

其他使用上的坑

如果使用file上传文件时，我们在结构体上定义如下：

1
2
3

type Form struct {
    File   *multipart.FileHeader `form:"file" json:"file"`
}

会报如下错误

1

Error parsing type definition 'dto.AddTenantReq': cannot find type definition: multipart.FileHeader

所以切记一点要加上swaggerignore:"true"，不让swagger去解析我们的结构体

1

File          *multipart.FileHeader `form:"file" json:"file" swaggerignore:"true"`

而file我们可以在单独的在@param中定义

1
2

//	@Param			file		formData	dto.AddTenantReq	true	"request body"
//	@Param			file		formData	file				false	"the tenant business path"

参考文档

https://github.com/swaggo/gin-swagger/issues/73 https://juejin.cn/post/7126802030944878600