之前寫過一篇使用Beego自動化api文檔的文章：Beego自動化文檔,隨著Beego的更新，1.7.0之后Beego自動化文檔的方法也有了更新，最顯著的更新是去掉了docs.go，使用了swagger.json,更加的符合swagger的特點。這篇文章是上一篇文章的修正和補充。

環(huán)境要求

需要安裝最新的Go語言環(huán)境，安裝Go可以參考Golang在Mac OS上的環(huán)境配置,還需要安裝最新的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的環(huán)境配置，Beego的版本等信息。

文檔的生成

在conf/app.conf中設置EnableDocs=true之后，仍然可以通過命令生成文檔:

bee generate docs

只是這里生成的不再是docs.go，而是符合swagger使用的兩個文檔:

swagger.json
swagger.yml

swagger.yml是swagger的契約文檔，根據(jù)這份文檔，可以描述出api的定義規(guī)則。而swagger.json描述的是一份符合swagger規(guī)則的api數(shù)據(jù)，通過這個json數(shù)據(jù)可以在swagger-ui中列出api文檔。
使用bee generate docs命令可以生成對于對于的兩個swagger文件，但是bee項目運行的時候是通過監(jiān)控文件，自動重新編譯項目的，自動重新編譯項目也能自動生成文檔是最好的，因此Beego在運行項目的時候添加了自動生成文檔的命令:

bee run -gendoc=true

這樣可以在每次項目重新運行的時候更新api文檔，不用重新運行命令:bee generate docs。

API文檔的訪問

更新swagger-ui是一件很麻煩的事情，所以在beego的運行命令中加入一個參數(shù)-downdoc=true:

bee run -downdoc=true

該命令會監(jiān)測swagger目錄下面是否有swagger-ui的文件，如果沒有就從github上面下載，下載的地址是: https://github.com/beego/swagger/archive/v2.zip
另外設置靜態(tài)文件夾的方法也有了變化，新的函數(shù)為:

beego.SetStaticPath("/swagger", "swagger")

設置完靜態(tài)文件夾之后可以通過url:http://127.0.0.1:8080/swagger/index.html訪問swagger文檔。打開該文檔會自動的請求swagger.json，發(fā)現(xiàn)請求的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文檔

路由解析與注解

路由解析仍然使用的是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()
}

總結(jié)

新版本的beego中對于swagger的支持更加的友好，也更加的swagger化了，采用了swagger.json和swagger.yml文件，不需要重新生成一個新的router文件了，這樣文檔部分的代碼更加的分離，使用swagger.yml可以更方便的生成訪問api的其他語言的代碼。

源代碼地址：https://github.com/jjz/go/tree/master/autodoc