beego自動化文檔

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:http://www.jianshu.com/p/943870134593
能夠使用intelliJ做爲go的IDE:[http://www.jianshu.com/p/9438...
也能夠使用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/就能夠看到自動化文檔的界面

也能夠運行下面命令改變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/beego_...
https://github.com/jjz/beego_...

參考文檔：http://beego.me/docs/advantag...