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