beego实现API自动化文档

beego的API自动化文档其实质就是使用swagger，但是功能还不是很完善。在使用时还有很多写法限制，否则自动化文档不会解析。例如：在配置接口路由必须按下面的写法。

// @APIVersion 1.0.0
// @Title beego Test API
// @Description beego has a very cool tools to autogenerate documents for your API
// @Contact [email protected]
// @TermsOfServiceUrl http://beego.me/
// @License Apache 2.0
// @LicenseUrl http://www.apache.org/licenses/LICENSE-2.0.html
package routers

import (
	"beeapi/controllers"

	"github.com/astaxie/beego"
)

func init() {
    ns := beego.NewNamespace("/v1",
        beego.NSNamespace("/object",
            beego.NSInclude(
                &controllers.ObjectController{},
            ),
        ),
        beego.NSNamespace("/user",
            beego.NSInclude(
                &controllers.UserController{},
            ),
        ),
    )
    beego.AddNamespace(ns)
}
// 路由注册使用namespace+include的写法，对于其他路由注册写法，beego不会完成解析。而且只支持二级解析，一级为版本号，二级分别表示应用模块

上面主要定义了接口的全局信息，在定义时，注释信息必须紧挨着包名之上。接着需要定义请求以及响应参数了。在Controller中定义。

package controllers

import (
	"beeapi/models"
	"encoding/json"

	"github.com/astaxie/beego"
)

// Operations about object
type ObjectController struct {
	beego.Controller
}

// @Title Create
// @Description create object
// @Param	body		body 	models.Object	true		"The object content"
// @Success 200 {string} models.Object.Id
// @Failure 403 body is empty
// @router / [post]
func (o *ObjectController) Post() {
	var ob models.Object
	json.Unmarshal(o.Ctx.Input.RequestBody, &ob)
	objectid := models.AddOne(ob)
	o.Data["json"] = map[string]string{"ObjectId": objectid}
	o.ServeJSON()
}

// @Title Get
// @Description find object by objectid
// @Param	objectId		path 	string	true		"the objectid you want to get"
// @Success 200 {object} models.Object
// @Failure 403 :objectId is empty
// @router /:objectId [get]
func (o *ObjectController) Get() {
	objectId := o.Ctx.Input.Param(":objectId")
	if objectId != "" {
		ob, err := models.GetOne(objectId)
		if err != nil {
			o.Data["json"] = err.Error()
		} else {
			o.Data["json"] = ob
		}
	}
	o.ServeJSON()
}

// @Title GetAll
// @Description get all objects
// @Success 200 {object} models.Object
// @Failure 403 :objectId is empty
// @router / [get]
func (o *ObjectController) GetAll() {
	obs := models.GetAll()
	o.Data["json"] = obs
	o.ServeJSON()
}

// @Title Update
// @Description update the object
// @Param	objectId		path 	string	true		"The objectid you want to update"
// @Param	body		body 	models.Object	true		"The body"
// @Success 200 {object} models.Object
// @Failure 403 :objectId is empty
// @router /:objectId [put]
func (o *ObjectController) Put() {
	objectId := o.Ctx.Input.Param(":objectId")
	var ob models.Object
	json.Unmarshal(o.Ctx.Input.RequestBody, &ob)

	err := models.Update(objectId, ob.Score)
	if err != nil {
		o.Data["json"] = err.Error()
	} else {
		o.Data["json"] = "update success!"
	}
	o.ServeJSON()
}

// @Title Delete
// @Description delete the object
// @Param	objectId		path 	string	true		"The objectId you want to delete"
// @Success 200 {string} delete success!
// @Failure 403 objectId is empty
// @router /:objectId [delete]
func (o *ObjectController) Delete() {
	objectId := o.Ctx.Input.Param(":objectId")
	models.Delete(objectId)
	o.Data["json"] = "delete success!"
	o.ServeJSON()
}

每个应用上面的注释，就是用来显示模块的作用。其中@Title描述API的含义，@Description描述API详细信息。
@Param是请求参数，有五列，使用空格或tab分割，分别表示的含义是：1. 参数名，2. 参数类型，例如formData，body，header等。3. 参数类型，4. 是否必须，5. 注释。
@Success表示成功后返回的信息，有三个参数，第一个状态码，第二个是返回类型，必须用{}包含。第三个是返回的对象或字符串信息，如果是对象，用{}包起来，如果是字符串，直接写内容。
@Failure描述失败返回信息，两个参数。第一个表示状态码，第二个是错误信息。
@router描述路由信息，两个参数，使用空格分隔。第一个是请求路由，第二个是支持的请求方法，需要放在[]之中，如果有多个，之间用逗号隔开。

例如上面的Put接口，返回的参数是一个结构体对象，models.Object。那么beego就会自动去models目录下，查找结构体Object。例如：

package models

type Object struct {
	ObjectId   string
	Score      int64
	PlayerName string
}

通过在router和controller中注释，我们已经完成了接口文档的准备工作。下面来看如何生成一个易于阅读的接口文档。
首先在工程的配置文件（app.conf）中增加设置:EnableDocs = true。
然后使用命令bee run -gendoc=true -downdoc=true来生成和下载swagger文档。如果正常的话，你应该可以看到工程目录下多了一个swagger目录，它是用来存放接口文档。
最后根据你本地启动的端口，访问不同的网址。例如我本地在8080端口启动服务，那么在浏览器访问http://localhost:8080/swagger/。


由于已经生成了swagger文件，所以你可以直接打开swagger目录下的index.html文件，同样可以看到自动生成的接口文档。

参考文章

1. API自动化文档