最近需要使用Go写一个Web API项目，可以使用Beego与Gin来写此类项目，还是非常方便的，这里就介绍一下使用Beego来创建的Web API项目并自动化文档的方法。

使用Gin创建API项目并自动化文档参见： 使用Gin编写Web API项目并自动化文档

一、准备环境

1go install github.com/beego/bee/v2@latest

二、创建API项目

1bee api api

在这里插入图片描述

１. 下载项目依赖

1$ cd api
2$ go mod tidy

在这里插入图片描述

此时项目目录结构如下：

 1$ tree
 2.
 3├── conf
 4│   └── app.conf
 5├── controllers
 6│   ├── object.go
 7│   └── user.go
 8├── go.mod
 9├── go.sum
10├── main.go
11├── models
12│   ├── object.go
13│   └── user.go
14├── routers
15│   └── router.go
16└── tests
17    └── default_test.go
18
196 directories, 10 files

２. 生成路由

1bee generate routers

在这里插入图片描述

该命令会生成routers/commentsRouter.go文件。

 1$ tree
 2.
 3├── conf
 4│   └── app.conf
 5├── controllers
 6│   ├── object.go
 7│   └── user.go
 8├── go.mod
 9├── go.sum
10├── main.go
11├── models
12│   ├── object.go
13│   └── user.go
14├── routers
15│   ├── commentsRouter.go
16│   └── router.go
17└── tests
18    └── default_test.go
19
206 directories, 11 files

此时可以在浏览器中浏览：http://127.0.0.1:8080/v1/user/

在这里插入图片描述 注意，这里不能使用https

三、自动化文档与测试

每次手动测试API还是比较繁琐的，为了方便测试，可以使用swagger来进行API辅助测试。

1bee run -gendoc=true -downdoc=true

在这里插入图片描述

此时默认使用的是https://petstore.swagger.io/v2/swagger.json配置文件

在这里插入图片描述

可以手动将前面的路径去掉，只保留swagger.json，然后测试，会发现有问题：

1	
2Failed to fetch.
3Possible Reasons:
4
5CORS
6Network Failure
7URL scheme must be "http" or "https" for CORS request.

在这里插入图片描述

需要修改swagger/index.html：

在这里插入图片描述

将url: "https://petstore.swagger.io/v2/swagger.json"替换成url: "/swagger/swagger.json"。再测试就正常了：

在这里插入图片描述

如何写注释，让swagger自动生成接口文档，可以参考： https://beego.wiki/zh-cn/docs/advantage/docs/