beego的API自動化文檔其實質就是使用swagger，但是功能還不是很完善。在使用時還有很多寫法限制，否則自動化文檔不會解析。例如：在配置接口路由必須按下面的寫法。
// @APIVersion 1.0.0
// @Title beego Test API
// @Description beego has a very cool tools to autogenerate documents for your API
// @Contact [email protected]
// @TermsOfServiceUrl http://beego.me/
// @License Apache 2.0
// @LicenseUrl http://www.apache.org/licenses/LICENSE-2.0.html
package routers
import (
"beeapi/controllers"
"github.com/astaxie/beego"
)
func init() {
ns := beego.NewNamespace("/v1",
beego.NSNamespace("/object",
beego.NSInclude(
&controllers.ObjectController{},
),
),
beego.NSNamespace("/user",
beego.NSInclude(
&controllers.UserController{},
),
),
)
beego.AddNamespace(ns)
}
// 路由注冊使用namespace+include的寫法，對于其他路由注冊寫法，beego不會完成解析。而且隻支援二級解析，一級為版本号，二級分别表示應用子產品
上面主要定義了接口的全局資訊，在定義時，注釋資訊必須緊挨着包名之上。接着需要定義請求以及響應參數了。在Controller中定義。
package controllers
import (
"beeapi/models"
"encoding/json"
"github.com/astaxie/beego"
)
// Operations about object
type ObjectController struct {
beego.Controller
}
// @Title Create
// @Description create object
// @Param body body models.Object true "The object content"
// @Success 200 {string} models.Object.Id
// @Failure 403 body is empty
// @router / [post]
func (o *ObjectController) Post() {
var ob models.Object
json.Unmarshal(o.Ctx.Input.RequestBody, &ob)
objectid := models.AddOne(ob)
o.Data["json"] = map[string]string{"ObjectId": objectid}
o.ServeJSON()
}
// @Title Get
// @Description find object by objectid
// @Param objectId path string true "the objectid you want to get"
// @Success 200 {object} models.Object
// @Failure 403 :objectId is empty
// @router /:objectId [get]
func (o *ObjectController) Get() {
objectId := o.Ctx.Input.Param(":objectId")
if objectId != "" {
ob, err := models.GetOne(objectId)
if err != nil {
o.Data["json"] = err.Error()
} else {
o.Data["json"] = ob
}
}
o.ServeJSON()
}
// @Title GetAll
// @Description get all objects
// @Success 200 {object} models.Object
// @Failure 403 :objectId is empty
// @router / [get]
func (o *ObjectController) GetAll() {
obs := models.GetAll()
o.Data["json"] = obs
o.ServeJSON()
}
// @Title Update
// @Description update the object
// @Param objectId path string true "The objectid you want to update"
// @Param body body models.Object true "The body"
// @Success 200 {object} models.Object
// @Failure 403 :objectId is empty
// @router /:objectId [put]
func (o *ObjectController) Put() {
objectId := o.Ctx.Input.Param(":objectId")
var ob models.Object
json.Unmarshal(o.Ctx.Input.RequestBody, &ob)
err := models.Update(objectId, ob.Score)
if err != nil {
o.Data["json"] = err.Error()
} else {
o.Data["json"] = "update success!"
}
o.ServeJSON()
}
// @Title Delete
// @Description delete the object
// @Param objectId path string true "The objectId you want to delete"
// @Success 200 {string} delete success!
// @Failure 403 objectId is empty
// @router /:objectId [delete]
func (o *ObjectController) Delete() {
objectId := o.Ctx.Input.Param(":objectId")
models.Delete(objectId)
o.Data["json"] = "delete success!"
o.ServeJSON()
}
每個應用上面的注釋，就是用來顯示子產品的作用。其中
@Title
描述API的含義，
@Description
描述API詳細資訊。
@Param
是請求參數，有五列，使用空格或tab分割，分别表示的含義是：1. 參數名，2. 參數類型，例如formData，body，header等。3. 參數類型，4. 是否必須，5. 注釋。
@Success
表示成功後傳回的資訊，有三個參數，第一個狀态碼，第二個是傳回類型，必須用{}包含。第三個是傳回的對象或字元串資訊，如果是對象，用{}包起來，如果是字元串，直接寫内容。
@Failure
描述失敗傳回資訊，兩個參數。第一個表示狀态碼，第二個是錯誤資訊。
@router
描述路由資訊，兩個參數，使用空格分隔。第一個是請求路由，第二個是支援的請求方法，需要放在[]之中，如果有多個，之間用逗号隔開。
例如上面的
Put
接口，傳回的參數是一個結構體對象，
models.Object
。那麼beego就會自動去
models
目錄下，查找結構體
Object
。例如：
package models
type Object struct {
ObjectId string
Score int64
PlayerName string
}
通過在router和controller中注釋，我們已經完成了接口文檔的準備工作。下面來看如何生成一個易于閱讀的接口文檔。
首先在工程的配置檔案（
app.conf
）中增加設定:
EnableDocs = true
。
然後使用指令
bee run -gendoc=true -downdoc=true
來生成和下載下傳swagger文檔。如果正常的話，你應該可以看到工程目錄下多了一個
swagger
目錄，它是用來存放接口文檔。
最後根據你本地啟動的端口，通路不同的網址。例如我本地在8080端口啟動服務，那麼在浏覽器通路
http://localhost:8080/swagger/
。
由于已經生成了
swagger
檔案，是以你可以直接打開
swagger
目錄下的
index.html
檔案，同樣可以看到自動生成的接口文檔。
參考文章
- API自動化文檔