gin 集成 Swagger

前言

一个好的项目工程，必然离不开一个好的 API 文档，如果要自己编写 API 文档，维护起来比较困难，而且难以保证一致性，因此我们要自动生成在线接口文档。

swaggo

swagger 在 java 里面，是一个非常流行的 api 组件，他们维护了 go 版本 swaggo，
可以通过 Swagger 2.0 自动生成RESTful API 文档。
swaggo 项目链接

安装

下载代码

# 最新版本
go get -u github.com/swaggo/swag/cmd/swag

# 可以加上版本号
go get -u github.com/swaggo/swag/cmd/swag@v1.8.8
1
2
3
4
5

另外还需要下载两个包

# gin-swagger 中间件
go get github.com/swaggo/gin-swagger

# swagger 内置文件
go get github.com/swaggo/gin-swagger/swaggerFiles
1
2
3
4
5

安装到 $PATH

若 $GOPATH 的 bin 目录下面没有 swag 文件，需要 go install

cd $GOPATH/pkg/mod/github.com/swaggo/swag@v1.8.8/cmd/swag
# 安装
go install
1
2
3

若 $GOROOT/bin 没有加入$PATH 中，需要将其可执行文件移动到 $GOBIN 下

mv $GOPATH/bin/swag /usr/local/go/bin
1

检查安装

出现这个情况，说明安装成功了

$ swag -v
swag version v1.8.8
1
2

gin 集成 swaggo

编写 api 注释

Swagger 中需要将相应的注释或注解编写到方法上，再利用生成器自动生成说明文件

gin-swagger 给出的范例：

// @Summary Add a new pet to the store
// @Description get string by ID
// @Accept  json
// @Produce  json
// @Param   some_id     path    int     true        "Some ID"
// @Success 200 {string} string	"ok"
// @Failure 400 {object} web.APIError "We need ID!!"
// @Failure 404 {object} web.APIError "Can not find ID"
// @Router /testapi/get-string-by-int/{some_id} [get]
1
2
3
4
5
6
7
8
9

参照 Swagger 的注解规范和范例去编写

// Register
// @Tags 用户管理
// @Summary 用户注册
// @Param username formData string true "username"
// @Param password formData string true "password"
// @Success 200 {string} json "{"code":"200","msg":"success","data":""}"
// @Router /register [post]
func Register(c *gin.Context) {}
1
2
3
4
5
6
7
8

路由

在完成了 api 注释的编写后，我们需要针对 swagger 新增初始化动作和对应的路由规则，才可以使用。在 routers/router.go 文件，增加 swagger 的路由：

func Router() *gin.Engine {
	r := gin.Default()
	
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))

	return r
}
1
2
3
4
5
6
7

生成

在项目目录下，执行 swag init

2022/12/04 15:27:52 Generate swagger docs....
2022/12/04 15:27:52 Generate general API Info, search dir:./
2022/12/04 15:27:52 create docs.go at  docs/docs.go
2022/12/04 15:27:52 create swagger.json at  docs/swagger.json
2022/12/04 15:27:52 create swagger.yaml at  docs/swagger.yaml
1
2
3
4
5

执行完成后会在项目根目录下生成 docs 目录，里面就是 api 文档相关的内容

docs/
├── docs.go
└── swagger
    ├── swagger.json
    └── swagger.yaml
1
2
3
4
5

可以看一下 json 的内容，其他的也是一样的，只是格式不同

查看文档

访问地址

http://127.0.0.1:8080/swagger/index.html
1

其他信息

在 main.go 方法上，可以增加一些其他信息，完善项目的信息

// @title Swagger Example API
// @version 1.0
// @description This is a sample server celler server.
// @termsOfService https://github.com/stream108

// @contact.name 一江溪水
// @contact.url https://github.com/stream1080
// @contact.email https://github.com/stream108

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host 127.0.0.1:8080
// @BasePath /api/v1
1
2
3
4
5
6
7
8
9
10
11
12
13
14