技术控

    今日:0| 主题:63445
收藏本版 (1)
最新软件应用技术尽在掌握

[其他] Beego自动化文档(最新版)

[复制链接]
ⅰ条生路 发表于 2016-11-27 14:48:24
210 0
之前写过一篇使用Beego自动化api文档的文章: Beego自动化文档 ,随着Beego的更新,1.7.0之后Beego自动化文档的方法也有了更新,最显著的更新是去掉了 docs.go ,使用了 swagger.json ,更加的符合swagger的特点。这篇文章是上一篇文章的修正和补充。
  环境要求

   需要安装最新的Go语言环境,安装Go可以参考 Golang在Mac OS上的环境配置 ,还需要安装最新的Beego框架。如果是你的Beego框架还是旧版本的就需要升级Beego:
  go get -u github.com/astaxie/beego
  go get -u github.com/beego/bee
  查看bee的最新版本:
  bee version
  1. | ___ \
  2. | |_/ /  ___   ___
  3. | ___ \ / _ \ / _ \
  4. | |_/ /|  __/|  __/
  5. \____/  \___| \___| v1.5.2
  6. ├── Beego     : 1.7.1
  7. ├── GoVersion : go1.7.3
  8. ├── GOOS      : darwin
  9. ├── GOARCH    : amd64
  10. ├── NumCPU    : 8
  11. ├── GOPATH    : /Users/jjz/Documents/go
  12. ├── GOROOT    : /usr/local/Cellar/go/1.7.3/libexec
  13. ├── Compiler  : gc
  14. └── Date      : Saturday, 26 Nov 2016
复制代码
可以从该命令中看到Go的环境配置,Beego的版本等信息。
  文档的生成

   在 conf/app.conf 中设置 EnableDocs=true 之后,仍然可以通过命令生成文档:
  bee generate docs
   只是这里生成的不再是 docs.go ,而是符合 swagger 使用的两个文档:
  1. swagger.json
  2. swagger.yml
复制代码
  swagger.yml 是swagger的契约文档,根据这份文档,可以描述出api的定义规则。而 swagger.json 描述的是一份符合swagger规则的api数据,通过这个json数据可以在 swagger-ui 中列出api文档。
   使用 bee generate docs 命令可以生成对于对于的两个swagger文件,但是bee项目运行的时候是通过监控文件,自动重新编译项目的,自动重新编译项目也能自动生成文档是最好的,因此Beego在运行项目的时候添加了自动生成文档的命令:
  bee run -gendoc=true
   这样可以在每次项目重新运行的时候更新api文档,不用重新运行命令: bee generate docs 。
  API文档的访问

   更新 swagger-ui 是一件很麻烦的事情,所以在beego的运行命令中加入一个参数 -downdoc=true :
  bee run -downdoc=true
   该命令会监测 swagger 目录下面是否有 swagger-ui 的文件,如果没有就从github上面下载,下载的地址是: https://github.com/beego/swagger/archive/v2.zip
  另外设置静态文件夹的方法也有了变化,新的函数为:
  beego.SetStaticPath("/swagger", "swagger")
   设置完静态文件夹之后可以通过url: http://127.0.0.1:8080/swagger/index.html 访问swagger文档。打开该文档会自动的请求 swagger.json ,发现请求的 swagger.json 文档地址为: http://127.0.0.1:8080/swagger/index.html/swagger.json ,需要把 swagger/index.html 中的swagger.json的地址设置为:
  url = "/swagger/swagger.json";
  再次访问swagger文档地址就可以看到API文档了:
   

Beego自动化文档(最新版)

Beego自动化文档(最新版)

  路由解析与注解

   路由解析仍然使用的是 namespace+Include :
  1. ns := beego.NewNamespace("/v1",
  2.         beego.NSNamespace("/object",
  3.             beego.NSInclude(
  4.                 &controllers.ObjectController{},
  5.             ),
  6.         ),
  7.         beego.NSNamespace("/user",
  8.             beego.NSInclude(
  9.                 &controllers.UserController{},
  10.             ),
  11.         ),
  12.     )
  13.     beego.AddNamespace(ns)
复制代码
而注解也是仍然采用以前的注解方式:
  1. // @Title createUser
  2. // @Description create users
  3. // @Param    body        body     models.User    true        "body for user content"
  4. // @Success 200 {int} models.User.Id
  5. // @Failure 403 body is empty
  6. // @router / [post]
  7. func (u *UserController) Post() {
  8.     var user models.User
  9.     json.Unmarshal(u.Ctx.Input.RequestBody, &user)
  10.     uid := models.AddUser(user)
  11.     u.Data["json"] = map[string]string{"uid": uid}
  12.     u.ServeJSON()
  13. }
复制代码
总结

   新版本的beego中对于swagger的支持更加的友好,也更加的swagger化了,采用了 swagger.json 和 swagger.yml 文件,不需要重新生成一个新的router文件了,这样文档部分的代码更加的分离,使用 swagger.yml 可以更方便的生成访问api的其他语言的代码。
   源代码地址: https://github.com/jjz/go/tree/master/autodoc
我要投稿

推荐阅读


回页顶回复上一篇下一篇回列表
手机版/c.CoLaBug.com ( 粤ICP备05003221号 | 粤公网安备 44010402000842号 )

© 2001-2017 Comsenz Inc.

返回顶部 返回列表