使用Gin编写Web API项目并自动化文档

最近需要使用Go写一个Web API项目，可以使用Beego与Gin来写此类项目，前文使用Beego创建API项目并自动化文档介绍了使用Beego来创建的Web API项目并自动化文档的方法。本文就介绍一下使用Gin来编写Web API项目并自动化文档。

一、创建项目

在创建Beego项目时，可以使用Beego的Bee命令来创建项目；而Gin没有类似的程序或者命令来创建项目，所以需要手动创建一个Go项目，新建一个目录，并进入该目录创建项目：

$ mkdir api
$ cd api
$ go mod init api
$ go mod tidy
1
2
3
4

二、添加代码

创建好项目后，即可使用VSCode或者Goland打开目录，开始工作了。项目结构可以参考Beego的Model－Controls方式：

$ tree
.
├── controls
│   └── user.go
├── go.mod
├── go.sum
├── main.go
├── models
│   └── user.go
└── routers
    └── router.go

4 directories, 6 files

1
2
3
4
5
6
7
8
9
10
11
12
13
14

这里直接把源码贴出来：

main.go：

package main

import (
	"api/routers"

	"github.com/gin-gonic/gin"
)

func main() {
	r := gin.Default()
	routers.InitRouters(r)
	r.Run(":8080")
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

routers/router.go：

package routers

import (
	"api/controls"

	"github.com/gin-gonic/gin"
)

func InitRouters(r *gin.Engine) {
	r.Group("v1").GET("users", controls.GetAllUsers)
}

1
2
3
4
5
6
7
8
9
10
11
12

models/user.go：

package models

var (
	UserList map[string]*User
)

type User struct {
	Id       string
	Username string
	Password string
	Profile  Profile
}

type Profile struct {
	Gender  string
	Age     int
	Address string
	Email   string
}

func init() {
	UserList = make(map[string]*User)
	u := User{"user_888888", "witton", "888888", Profile{"male", 20, "成都", "witton@163.com"}}
	UserList["user_888888"] = &u
}

func GetAllUsers() map[string]*User {
	return UserList
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

controls/user.go：

package controls

import (
	"api/models"
	"net/http"

	"github.com/gin-gonic/gin"
)

func GetAllUsers(c *gin.Context) {
	c.JSON(http.StatusOK, models.GetAllUsers())
}

1
2
3
4
5
6
7
8
9
10
11
12
13

添加好代码后，执行：

$ go mod tidy
1

运行项目后，可以在浏览器中访问：http://127.0.0.1:8080/v1/users

就可以看到结果了。

三、自动化文档

与使用Beego创建API项目并自动化文档中说的一样，为了方便测试，需要引入swagger来自动化文档。

1. 安装最新swag

使用下面的命令安装最新的swag

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

2. 编写swag注释

修改controls/user.go，在GetAllUsers函数上添加注释：

package controls

import (
	"api/models"
	"net/http"

	"github.com/gin-gonic/gin"
)

// @Summary 获取所有用户
// @Produce  json
// @Success 200 {object} models.User
// @Router /v1/users [get]
func GetAllUsers(c *gin.Context) {
	c.JSON(http.StatusOK, models.GetAllUsers())
}

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

关于注释的格式，可以参考：
https://gitee.com/acrowise/swag
https://github.com/swaggo/swag/blob/master/README_zh-CN.md

3. 生成文档

使用swag init命令生成文档：

$ swag init
2024/05/06 14:36:57 Generate swagger docs....
2024/05/06 14:36:57 Generate general API Info, search dir:./
2024/05/06 14:36:57 create docs.go at docs/docs.go
2024/05/06 14:36:57 create swagger.json at docs/swagger.json
2024/05/06 14:36:57 create swagger.yaml at docs/swagger.yaml

1
2
3
4
5
6
7

生成文档后，会在根目录下创建一个docs目录，所有生成的文件都放在里面。

$ tree
.
├── controls
│   └── user.go
├── docs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── go.mod
├── go.sum
├── main.go
├── models
│   └── user.go
└── routers
    └── router.go

5 directories, 9 files

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

4. 添加路由

routers/router.go中添加路由：

r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
1

routers/router.go完整代码：

package routers

import (
	"api/controls"

	_ "api/docs"

	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

func InitRouters(r *gin.Engine) {
	r.Group("v1").GET("users", controls.GetAllUsers)
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}

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

需要注意的是：swaggerFiles已经改名了，不再是"github.com/swaggo/gin-swagger/swaggerFiles"，如果导入"github.com/swaggo/gin-swagger/swaggerFiles"，则会报错：

go: finding module for package github.com/swaggo/gin-swagger/swaggerFiles
go: api/routers imports
        github.com/swaggo/gin-swagger/swaggerFiles: module github.com/swaggo/gin-swagger@latest found (v1.6.0), but does not contain package github.com/swaggo/gin-swagger/swaggerFiles 
1
2
3

需要导入"github.com/swaggo/files"。

5. 运行测试

执行go mod tidy下载依赖后再启动项目，在浏览器中访问：http://127.0.0.1:8080/swagger/index.html，即可看到页面：

测试一下API：

可以看到正常的结果。