beego自动化文档

姜家志 · · 7783 次点击 · · 开始浏览    
这是一个创建于 的文章,其中的信息可能已经有所发展或是发生改变。

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

beego是什么?

beego是一个快速开发go应用http框架go 语言技术大牛ASTA谢的开源项目。
beego可以用来快速开发APIWeb以及后端服务等各种应用,是一个RESTFul的框架,主要设计灵感来源于tornadosinatraflask这三个框架,结合了Go本身的一些特性(interfacestruct继承等)而设计的。
beego结合swagger就能实现自动化的文档。

Swagger是什么?

Swagger 是一个规范和一套完整的框架,用于生成描述调用以及可视化 RESTful 风格Web 服务
Swagger的总体目标是使客户端和文件系统服务器以同样的速度来更新,方法,参数和模型紧密集成到服务器端的代码中,允许API始终保持同步。
Swagger 让部署管理和使用API从未如此简单。

自动文档的好处?

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

使用指南

首先安装go:http://www.jianshu.com/p/943870134593
可以使用intelliJ作为go的IDE:http://www.jianshu.com/p/943870134593
也可以使用Atom作用go的IDE:http://www.jianshu.com/p/c1d8cf274ec7

安装beego:http://beego.me/quickstart
使用go get安装beego:

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:https://github.com/beego/swagger
也可以下载最新的Swagger:http://swagger.io/

放到项目的根目录下面,目录名称为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监控文件系统,这样在开发的过程中可以实时的看到项目修改之后的效果。

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


swagger

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

bee run docs -docport=8888

注解

beego的文档注解包括两种:全局注解和应用注解.
全局注释,必须放在router.go的最顶部,包括:

    @APIVersion
    @Title
    @Description
    @Contact
    @TermsOfServiceUrl
    @License
    @LicenseUrl

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

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

测试项目地址:https://github.com/jjz/go/tree/master/autodoc

参考文档:http://beego.me/docs/advantage/docs.md


有疑问加站长微信联系(非本文作者)

本文来自:简书

感谢作者:姜家志

查看原文:beego自动化文档

入群交流(和以上内容无关):加入Go大咖交流群,或添加微信:liuxiaoyan-s 备注:入群;或加QQ群:692541889

7783 次点击  
加入收藏 微博
暂无回复
添加一条新回复 (您需要 登录 后才能回复 没有账号 ?)
  • 请尽量让自己的回复能够对别人有帮助
  • 支持 Markdown 格式, **粗体**、~~删除线~~、`单行代码`
  • 支持 @ 本站用户;支持表情(输入 : 提示),见 Emoji cheat sheet
  • 图片支持拖拽、截图粘贴等方式上传