最近需要使用Go写一个Web API项目，可以使用Beego与Gin来写此类项目，前文使用Beego创建API项目并自动化文档介绍了使用Beego来创建的Web API项目并自动化文档的方法。本文就介绍一下使用Gin来编写Web API项目并自动化文档。
一、创建项目
在创建Beego项目时，可以使用Beego的Bee命令来创建项目；而Gin没有类似的程序或者命令来创建项目，所以需要手动创建一个Go项目，新建一个目录，并进入该目录创建项目：
bash
$ mkdir api
$ cd api
$ go mod init api
$ go mod tidy二、添加代码
创建好项目后，即可使用VSCode或者Goland打开目录，开始工作了。项目结构可以参考Beego的Model－Controls方式：
bash
$ tree
.
├── controls
│ └── user.go
├── go.mod
├── go.sum
├── main.go
├── models
│ └── user.go
└── routers
└── router.go
4 directories, 6 files这里直接把源码贴出来：
main.go：
go
package main
import (
"api/routers"
"github.com/gin-gonic/gin"
)
func main() {
r := gin.Default()
routers.InitRouters(r)
r.Run(":8080")
}routers/router.go：
go
package routers
import (
"api/controls"
"github.com/gin-gonic/gin"
)
func InitRouters(r *gin.Engine) {
r.Group("v1").GET("users", controls.GetAllUsers)
}models/user.go：
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, "成都", "[email protected]"}}
UserList["user_888888"] = &u
}
func GetAllUsers() map[string]*User {
return UserList
}controls/user.go：
go
package controls
import (
"api/models"
"net/http"
"github.com/gin-gonic/gin"
)
func GetAllUsers(c *gin.Context) {
c.JSON(http.StatusOK, models.GetAllUsers())
}添加好代码后，执行：
bash
$ go mod tidy运行项目后，可以在浏览器中访问：http://127.0.0.1:8080/v1/users
就可以看到结果了。
三、自动化文档
与使用Beego创建API项目并自动化文档中说的一样，为了方便测试，需要引入swagger来自动化文档。
1. 安装最新swag
使用下面的命令安装最新的swag
bash
go install github.com/swaggo/swag/cmd/swag@latest2. 编写swag注释
修改controls/user.go，在GetAllUsers函数上添加注释：
go
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())
}关于注释的格式，可以参考：
https://gitee.com/acrowise/swag
https://github.com/swaggo/swag/blob/master/README_zh-CN.md
3. 生成文档
使用swag init命令生成文档：
bash
$ 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目录，所有生成的文件都放在里面。
bash
$ 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 files4. 添加路由
routers/router.go中添加路由：
bash
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))routers/router.go完整代码：
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))
}需要注意的是：swaggerFiles已经改名了，不再是"github.com/swaggo/gin-swagger/swaggerFiles"，如果导入"github.com/swaggo/gin-swagger/swaggerFiles"，则会报错：
bash
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 需要导入"github.com/swaggo/files"。
5. 运行测试
执行go mod tidy下载依赖后再启动项目，在浏览器中访问：http://127.0.0.1:8080/swagger/index.html，即可看到页面：
测试一下API：
可以看到正常的结果。