go 语言使用Beego 生成 swagger文档

构建Beego 简单应用

1. 安装 bee cli
   go get -u github.com/beego/bee/v2
2. 进入 GOPATH 下
   cd $GOPATH/src
3. 生成一个简易项目
   bee api http_server

配置beego

1. 在 conf/app.conf

# 仅在dev模式下开启swagger
runmode=dev 
# 确保swagger开启
EnableDocs=true
1
2
3
4

配置swagger 并启动

1. 运行服务，并下载swagger 网页文件

bee run -gendoc=true -downdoc=true
1

2. 如果网络错误无法下载，手动下载后放在项目下

wget https://codeload.github.com/beego/swagger/zip/refs/tags/v4.6.1
1

3. 再次运行

bee run -gendoc=true -downdoc=true
1

4. 打开 http://127.0.0.1:8080
5. 如果提示 404, 再运行文件下添加下列代码

if beego.BConfig.RunMode == "dev" {
    beego.BConfig.WebConfig.DirectoryIndex = true
    beego.BConfig.WebConfig.StaticDir["/swagger"] = "swagger"
}
1
2
3
4

6. 打开网页后，在内网情况下无法访问
   Failed to load API definition
7. 手动下载swagger.json, 同样也放在项目下
   wget https://petstore.swagger.io/v2/swagger.json
8. 接着在网页中输入 swagger.json，即可启动
9. 刷新后仍会报错，修改swagger/index.html

# 找到 SwaggerUIBundle({
url: "wget https://petstore.swagger.io/v2/swagger.json"
# 改为
url: "swagger.json"
1
2
3
4

swagger 文档编写

简单方式

// @route / [get]
func (c *TestController) Get() {
}
1
2
3

添加API相应信息

// @Title 测试API
// @Description 返回测试文本
// @route / [get]
func (c *TestController) Get() {
}
1
2
3
4
5

复杂注释及解释

应用注释
接下来就是我们最重要的注释了，就是我们定义的，我们先来看一个例子：

package controllers

import "github.com/beego/beego/v2/server/web"

// CMS API
type CMSController struct {
    web.Controller
}

func (c *CMSController) URLMapping() {
    c.Mapping("StaticBlock", c.StaticBlock)
    c.Mapping("Product", c.Product)
}

// @Title getStaticBlock
// @Description get all the staticblock by key
// @Param    key        path     string    true        "The email for login"
// @Success 200 {object} models.ZDTCustomer.Customer 
// @Failure 400 Invalid email supplied
// @Failure 404 User not found
// @router /staticblock/:key [get]
func (c *CMSController) StaticBlock() {

}

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

注：如果希望model中struct对象的某些字段在接口文档中不显示，可以使用 json:“-” 标记，如下：
Id int orm:"column(id);auto" json:"-"

// @Title Get Product list
// @Description Get Product list by some info
// @Success 200 {object} models.ZDTProduct.ProductList
// @Param    category_id        query    int    false        "category id"
// @Param    brand_id    query    int    false        "brand id"
// @Param    query    query    string     false        "query of search"
// @Param    segment    query    string     false        "segment"
// @Param    sort     query    string     false        "sort option"
// @Param    dir     query    string     false        "direction asc or desc"
// @Param    offset     query    int        false        "offset"
// @Param    limit     query    int        false        "count limit"
// @Param    price             query    float        false        "price"
// @Param    special_price     query    bool        false        "whether this is special price"
// @Param    size             query    string        false        "size filter"
// @Param    color             query    string        false        "color filter"
// @Param    format             query    bool        false        "choose return format"
// @Failure 400 no enough input
// @Failure 500 get products common error
// @router /products [get]
func (c *CMSController) Product() {

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

首先是 CMSController 定义上面的注释，这个是用来显示这个模块的作用。接下来就是每一个函数上面的注释，这里列出来支持的各种注释：

@Title

这个 API 所表达的含义，是一个文本，空格之后的内容全部解析为 title

@Description

这个 API 详细的描述，是一个文本，空格之后的内容全部解析为 Description

@Param

参数，表示需要传递到服务器端的参数，有五列参数，使用空格或者 tab 分割，五个分别表示的含义如下

参数名
参数类型，可以有的值是 formData、query、path、body、header，formData 表示是 post 请求的数据，query 表示带在 url 之后的参数，path 表示请求路径上得参数，例如上面例子里面的 key，body 表示是一个 raw 数据请求，header 表示带在 header 信息中得参数。
参数类型
是否必须
注释
@Success

成功返回给客户端的信息，三个参数，第一个是 status code。第二个参数是返回的类型，必须使用 {} 包含，第三个是返回的对象或者字符串信息，如果是 {object} 类型，那么 bee 工具在生成 docs 的时候会扫描对应的对象，这里填写的是想对你项目的目录名和对象，例如 models.ZDTProduct.ProductList 就表示 /models/ZDTProduct 目录下的 ProductList 对象。

三个参数必须通过空格分隔

@Failure

失败返回的信息，包含两个参数，使用空格分隔，第一个表示 status code，第二个表示错误信息

@router

路由信息，包含两个参数，使用空格分隔，第一个是请求的路由地址，支持正则和自定义路由，和之前的路由规则一样，第二个参数是支持的请求方法,放在 [] 之中，如果有多个方法，那么使用 , 分隔。

访问 404

1. 首先检查路由文件是否导入启动文件 main.go
2. 其次如果是注解路由，或者自动路由，检查文件 comment_routers.go 有没有生成，或者生成有没有错误
   • 如果有出现问题，可以使用命令 bee generate routers 重新生成路由
3. 另外就是注解路由中出现，注解冲突的情况，需要解决
4. 注解路由自动生成需要放在 GOPATH/src 下 才会自动生成，注意 commentsRouter.go 中有没有相应的路由，这是个 bug
5. 最好还是使用那种简单的路由方式 NSRouter ，不容易出问题

参考文档

1. beego v2 开发文档
2. beego 使用swagger 掘金
3. beego 使用swagger 知乎