beego api自动生成文档

必须设置在 routers/router.go 中，文件的注释，最顶部：

// @APIVersion 1.0.0
// @Title mobile API
// @Description mobile has every tool to get any job done, so codename for the new mobile APIs.
// @Contact astaxie@gmail.com
package routers

路由解析

目前自动化文档只支持如下的写法的解析，其他写法函数不会自动解析，即 namespace+Include 的写法，而且只支持二级解析，一级版本号，二级分别表示应用模块

注解路由

router.go

	func init() {
	ns :=
		beego.NewNamespace("/v1",
			beego.NSNamespace("/user",
				beego.NSInclude(
					&controllers.UserController{},
				),
			),
		)
	beego.AddNamespace(ns)
}

controllers/user.go
在方法上边加入注释：// @router /login [Post]
前端请求接口：/v1/user/login

type UserController struct {
	beego.Controller
}

type Result struct {
	Status int `json:"status"`
	Msg string `json:"msg"`
}
// @Title 登陆
// @Description 用户登陆接口
// @Param phone formData string false "手机号"
// @Param id formData string false "用户id"
// @Param nickName formData string false "用户名称"
// @Success 200 {object} controllers.user.Result
// @Failure 404 接口未找到
// @Failure 504 接口超时
// @router /login [Post]
func (this *UserController) Post() {
	var ob models.SysUser
	json.Unmarshal(this.Ctx.Input.RequestBody, &ob)
	flag := models.QuerUser(&ob)
	fmt.Print(flag)
	result := Result{0, "asd"}
	this.Data["json"] = &result
	this.ServeJSON()
}

应用注释

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

使用

要使得文档工作，你需要做几个事情，

• 第一开启应用内文档开关，在配置文件中设置：EnableDocs = true,
  然后在你的 main.go 函数中引入 _ “beeapi/docs”（beego 1.7.0 之后版本不需要添加该引用）。
• 这样你就已经内置了 docs 在你的 API 应用中，然后你就使用 bee run -gendoc=true -downdoc=true,让我们的 API 应用跑起来，-gendoc=true 表示每次自动化的 build 文档，-downdoc=true 就会自动的下载 swagger 文档查看器

main.go

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

打开127.0.0.1:8080/swagger就可以查看效果

效果

字段描述

我们发现字段都是optional的,而且没有任何针对字段的描述，其实我们可以在对象定义里面增加如下的tag：

type SysUser struct {
	Id         int    `json:"id" required:"true" description:"用户id"`
	NickName   string `json:"nickName" required:"true" description:"用户昵称"`
	Phone      string `json:"phone" required:"true" description:"手机号"`
	CreateTime string `json:"createTime" required:"true" description:"创建时间"`
	UpdateTime string `json:"updateTime" required:"true" description:"更新时间"`
}