beego是什么？

beego是一个快速开发go应用的http框架，go 语言技术大牛ASTA谢的开源项目。

beego可以用来快速开发API、Web以及后端服务等各种应用，是一个RESTFul的框架，主要设计灵感来源于tornado、sinatra、flask这三个框架，结合了Go本身的一些特性(interface、struct继承等)而设计的。

beego结合swagger就能实现自动化的文档。

Swagger是什么？

Swagger 是一个规范和一套完整的框架，用于生成、描述、调用以及可视化 RESTful 风格的 Web 服务。

Swagger的总体目标是使客户端和文件系统服务器以同样的速度来更新，方法，参数和模型紧密集成到服务器端的代码中，允许API始终保持同步。

Swagger 让部署管理和使用API从未如此简单。

自动文档的好处？

1. 不用手动写文档了，通过注解就可以自动化文档

2. 文档和代码同步更新，代码更新之后不需要再更新文档

3. 浏览器友好

4. 使用Swagger框架可以调试API，在浏览器端可以看到更多的`request`和`response`信息

使用指南

go get github.com/astaxie/beego

安装bee工具:

go get github.com/beego/bee

未了方面可以把$GOPATH/bin加入到你的$PATH变量中:

export PATH=$PATH:$GOPATH/bin

创建一个beego项目

使用bee工具可以方便的创建，管理，运行，打包beego项目:

bee api beeapi

必须在$GOPATH/src的目录下创建项目。

为该项目指定Swagger目录:

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

放到项目的根目录下面，目录名称为swagger，和上面的配置一致。

路由解析

目前自动化文档的路由规则只支持NewNamespace写法的解析，其他写法函数不会自动解析为文章，就是namespace+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

文档的生成在 docs文件的init函数中调用的，因此必须在main中导入docs文件，这样就会调用docs的init函数

_ "beeapi/docs"

运行程序：

bee run watchall true

bee run命令是监控beego的项目文件，通过fsnotify监控文件系统，这样在开发的过程中可以实时的看到项目修改之后的效果。

swagger

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

bee run docs -docport=8888

注解

beego的文档注解包括两种:全局注解和应用注解.

全局注释，必须放在router.go的最顶部,包括:

@APIVersion

@Title

@Description

@Contact

@TermsOfServiceUrl

@License

@LicenseUrl

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

@title

@Description

@Param

@Success

@Failure

@router