beego框架使用笔记,Beego自动化文档

2019-10-08 17:19 来源:未知

Beego介绍

  beego我认为是go初学者比较容易上手的一门MVC Web框架。简单易懂,最重要的一点就是提供了中文文档,这对于我这种英语能力比较差的人来说就是福音。

  beego的官网上是这么介绍beego的:“beego 是一个快速开发 Go 应用的 HTTP 框架,他可以用来快速开发 API、Web 及后端服务等各种应用,是一个 RESTful 的框架,主要设计灵感来源于 tornado、sinatra 和 flask 这三个框架,但是结合了 Go 本身的一些特性(interface、struct 嵌入等)而设计的一个框架”。从中可以看出beego可以快速开发API接口、可以实现服务端的各种应用

之前写过一篇使用Beego自动化api文档的文章:Beego自动化文档,随着Beego的更新,1.7.0之后Beego自动化文档的方法也有了更新,最显著的更新是去掉了docs.go,使用了swagger.json,更加的符合swagger的特点。这篇文章是上一篇文章的修正和补充。

安装:

go get github.com/astaxie/beego

Beego官网

  beego官网 :

  github : 

环境要求

需要安装最新的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

| ___ 
| |_/ /  ___   ___
| ___  / _  / _ 
| |_/ /|  __/|  __/
____/  ___| ___| v1.5.2

├── Beego     : 1.7.1
├── GoVersion : go1.7.3
├── GOOS      : darwin
├── GOARCH    : amd64
├── NumCPU    : 8
├── GOPATH    : /Users/jjz/Documents/go
├── GOROOT    : /usr/local/Cellar/go/1.7.3/libexec
├── Compiler  : gc
└── Date      : Saturday, 26 Nov 2016

可以从该命令中看到Go的环境配置,Beego的版本等信息。

常见问题:

  • git 没有安装,请自行安装不同平台的 git
  • git https 无法获取,请配置本地的 git,关闭 https 验证:
git config --global http.sslVerify false

Beego安装

  beego 包含一些示例应用程序以帮您学习并使用 beego 应用框架。

  您需要安装 Go 1.1+ 以确保所有功能的正常使用。

  你需要安装 Beego 和 Bee 的开发工具:

$ go get github.com/astaxie/beego
$ go get github.com/beego/bee

  注意:

  1. beege和bee是两个概念。beego是框架,bee是工具,是命令。
  2. 在安装Beego前,先确认是否将$GOPATH/bin写入GO环境中。

文档的生成

conf/app.conf中设置EnableDocs=true之后,仍然可以通过命令生成文档:

bee generate docs

只是这里生成的不再是docs.go,而是符合swagger使用的两个文档:

swagger.json
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

升级

go get -u github.com/astaxie/beego

Bee工具的使用

 安装完成Bee后,在控制台输入bee

Bee is a tool for managing beego framework.

Usage:

    bee command [arguments]

The commands are:

    new         Create a Beego application
    run         run the app and start a Web server for development
    pack        Compress a beego project into a single file
    api         create an API beego application
    hprose      create an rpc application use hprose base on beego framework
    bale        packs non-Go files to Go source files
    version     prints the current Bee version
    generate    source code generator
    migrate     run database migrations
    fix         fix the beego application to make it compatible with beego 1.6

Use "bee help [command]" for more information about a command.

Additional help topics:


Use "bee help [topic]" for more information about that topic.

主要有以上10个命令,下面说几个常用的命令

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文档了:

swagger文档

bee 工具简介

bee 工具是一个为了协助快速开发 beego 项目而创建的项目,通过 bee 您可以很容易的进行 beego 项目的创建、热编译、开发、测试、和部署。

 new命令

  new 命令是新建一个 Web 项目,我们在命令行下执行 bee new <项目名> 就可以创建一个新的项目。但是注意该命令必须在 $GOPATH/src 下执行。最后会在 $GOPATH/src 相应目录下生成如下目录结构的项目:

bogon:src zuxingyu$ bee new cnblogs
______
| ___ 
| |_/ /  ___   ___
| ___  / _  / _ 
| |_/ /|  __/|  __/
____/  ___| ___| v1.5.2
2016/10/31 22:16:11 [INFO] Creating application...
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/conf/
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/controllers/
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/models/
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/routers/
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/tests/
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/static/
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/static/js/
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/static/css/
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/static/img/
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/views/
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/conf/app.conf
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/controllers/default.go
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/views/index.tpl
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/routers/router.go
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/tests/default_test.go
    create     /Users/zuxingyu/Documents/GoWorkSpace/src/cnblogs/main.go
2016/10/31 22:16:11 [SUCC] New application successfully created!

  这样一个beego框架的Go项目就生成了

路由解析与注解

路由解析仍然使用的是namespace+Include

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

而注解也是仍然采用以前的注解方式:

// @Title createUser
// @Description create users
// @Param   body        body    models.User true        "body for user content"
// @Success 200 {int} models.User.Id
// @Failure 403 body is empty
// @router / [post]
func (u *UserController) Post() {
    var user models.User
    json.Unmarshal(u.Ctx.Input.RequestBody, &user)
    uid := models.AddUser(user)
    u.Data["json"] = map[string]string{"uid": uid}
    u.ServeJSON()
}

bee 工具的安装

go get github.com/beego/bee

安装完之后,bee 可执行文件默认存放在 $GOPATH/bin 里面,所以您需要把 $GOPATH/bin 添加到您的环境变量中,才可以进行下一步。

%GOPATH%bin;

常见问题:

  • bee: command not found

请你把GOPATH/bin下的bee.exe 拷贝到 GOROOT/bin里面,然后运行 bee


TAG标签:
版权声明:本文由金沙澳门官网4166发布于中国史,转载请注明出处:beego框架使用笔记,Beego自动化文档