因为beego的更新，一些使用自动化文档的方法也有了更新，请参考：http://www.jianshu.com/p/0dc261bc5cea

beego是什么？

beegogo 语言beegoRESTFultornadosinatraflaskinterfacestructbeegoswagger

Swagger是什么？

Swagger生成描述调用可视化Swagger方法，参数和模型允许APISwagger

自动文档的好处？

1. 不用手动写文档了，通过注解就可以自动化文档
2. 文档和代码同步更新，代码更新之后不需要再更新文档
3. 浏览器友好
4. 使用Swagger框架可以调试API，在浏览器端可以看到更多的`request`和`response`信息

使用指南

intelliJAtom
go get

go get github.com/astaxie/beego

安装bee工具:

go get github.com/beego/bee

$GOPATH/bin$PATH

export PATH=$PATH:$GOPATH/bin

创建一个beego项目

beebeego

bee api beeapi

$GOPATH/srcSwagger

beego.StaticDir["/swagger"] = "swagger"

SwaggerSwagger
根目录swagger

路由解析

NewNamespacenamespace+Include
    ns := beego.NewNamespace("/v1",
        beego.NSNamespace("/object",
            beego.NSInclude(
                &controllers.ObjectController{},
            ),
        ),
        beego.NSNamespace("/user",
            beego.NSInclude(
                &controllers.UserController{},
            ),
        ),
    )
    beego.AddNamespace(ns)

生成文档

conf/app.conf

EnableDocs = true

docs

bee generate docs

docsinit函数docsinit函数
  _ "beeapi/docs"

运行程序：

bee run watchall true

bee runfsnotify

打开http://127.0.0.1:8080/swagger/就可以看到自动化文档的界面

也可以运行下面命令改变docs的端口号：

bee run docs -docport=8888

注解

beego全局注释router.go
    @APIVersion
    @Title
    @Description
    @Contact
    @TermsOfServiceUrl
    @License
    @LicenseUrl

应用注释，需要放在对应方法的上面,包括:

    @title
    @Description
    @Param
    @Success
    @Failure
    @router