使用Gin编写Web API项目并自动化文档-编程知识

使用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

二、添加代码

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

$ tree
.
├── controls
│   └── user.go
├── go.mod
├── go.sum
├── main.go
├── models
│   └── user.go
└── routers└── router.go4 directories, 6 files

这里直接把源码贴出来：

`main.go`：

package mainimport ("api/routers""github.com/gin-gonic/gin"
)func main() {r := gin.Default()routers.InitRouters(r)r.Run(":8080")
}

`routers/router.go`：

package routersimport ("api/controls""github.com/gin-gonic/gin"
)func InitRouters(r *gin.Engine) {r.Group("v1").GET("users", controls.GetAllUsers)
}

`models/user.go`：

package modelsvar (UserList map[string]*User
)type User struct {Id       stringUsername stringPassword stringProfile  Profile
}type Profile struct {Gender  stringAge     intAddress stringEmail   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
}

`controls/user.go`：

package controlsimport ("api/models""net/http""github.com/gin-gonic/gin"
)func GetAllUsers(c *gin.Context) {c.JSON(http.StatusOK, models.GetAllUsers())
}

添加好代码后，执行：

$ go mod tidy

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

在这里插入图片描述

就可以看到结果了。

三、自动化文档

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

1. 安装最新swag

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

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

2. 编写swag注释

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

package controlsimport ("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())
}

关于注释的格式，可以参考：
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

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

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

4. 添加路由

routers/router.go中添加路由：

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

routers/router.go完整代码：

package routersimport ("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))
}

需要注意的是：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 importsgithub.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

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