构建Beego 简单应用
- 安装 bee cli
go get -u github.com/beego/bee/v2
- 进入 GOPATH 下
cd $GOPATH/src
- 生成一个简易项目
bee api http_server
配置beego
- 在 conf/app.conf
# 仅在dev模式下开启swagger
runmode=dev
# 确保swagger开启
EnableDocs=true
配置swagger 并启动
- 运行服务,并下载swagger 网页文件
bee run -gendoc=true -downdoc=true
- 如果网络错误无法下载,手动下载后放在项目下
wget https://codeload.github.com/beego/swagger/zip/refs/tags/v4.6.1
- 再次运行
bee run -gendoc=true -downdoc=true
- 打开 http://127.0.0.1:8080
- 如果提示 404, 再运行文件下添加下列代码
if beego.BConfig.RunMode == "dev" {
beego.BConfig.WebConfig.DirectoryIndex = true
beego.BConfig.WebConfig.StaticDir["/swagger"] = "swagger"
}
- 打开网页后,在内网情况下无法访问
Failed to load API definition
- 手动下载swagger.json, 同样也放在项目下
wget https://petstore.swagger.io/v2/swagger.json
- 接着在网页中输入 swagger.json,即可启动
- 刷新后仍会报错,修改swagger/index.html
# 找到 SwaggerUIBundle({
url: "wget https://petstore.swagger.io/v2/swagger.json"
# 改为
url: "swagger.json"
swagger 文档编写
简单方式
// @route / [get]
func (c *TestController) Get() {
}
添加API相应信息
// @Title 测试API
// @Description 返回测试文本
// @route / [get]
func (c *TestController) Get() {
}
复杂注释及解释
应用注释
接下来就是我们最重要的注释了,就是我们定义的,我们先来看一个例子:
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() {
}
注:如果希望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() {
}
首先是 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
- 首先检查路由文件是否导入启动文件 main.go
- 其次如果是注解路由,或者自动路由,检查文件 comment_routers.go 有没有生成,或者生成有没有错误
- 如果有出现问题,可以使用命令 bee generate routers 重新生成路由
- 另外就是注解路由中出现,注解冲突的情况,需要解决
- 注解路由自动生成需要放在 GOPATH/src 下 才会自动生成,注意 commentsRouter.go 中有没有相应的路由,这是个 bug
- 最好还是使用那种简单的路由方式 NSRouter ,不容易出问题