[TOC]
# API自動化文檔
自動化文檔一直是我夢想中的一個功能,這次借著公司的項目終于實現了出來,我說過beego不僅僅要讓開發API快,而且讓使用API的用戶也能快速的使用我們開發的API,這個就是我開發這個項目的初衷。好了,趕緊動手實踐一把吧,首先`bee api beeapi`新建一個API應用做起來吧。
# API全局設置
必須設置在`routers/router.go`中,文件的注釋,最頂部:
```
// @APIVersion 1.0.0
// @Title mobile API
// @Description mobile has every tool to get any job done, so codename for the new mobile APIs.
// @Contact astaxie@gmail.com
package routers
```
全局的注釋如上所示,是顯示給全局應用的設置信息,有如下這些設置
- @APIVersion
- @Title
- @Description
- @Contact
- @TermsOfServiceUrl
- @License
- @LicenseUrl
## 路由解析須知
目前自動化文檔只支持如下的寫法的解析,其他寫法函數不會自動解析,即namespace+Include的寫法,而且只支持二級解析,一級版本號,二級分別表示應用模塊
```
func init() {
ns :=
beego.NewNamespace("/v1",
beego.NSNamespace("/customer",
beego.NSInclude(
&controllers.CustomerController{},
&controllers.CustomerCookieCheckerController{},
),
),
beego.NSNamespace("/catalog",
beego.NSInclude(
&controllers.CatalogController{},
),
),
beego.NSNamespace("/newsletter",
beego.NSInclude(
&controllers.NewsLetterController{},
),
),
beego.NSNamespace("/cms",
beego.NSInclude(
&controllers.CMSController{},
),
),
beego.NSNamespace("/suggest",
beego.NSInclude(
&controllers.SearchController{},
),
),
)
beego.AddNamespace(ns)
}
```
## 應用注釋
接下來就是我們最重要的注釋了,就是我們定義的,我們先來看一個例子:
```
package controllers
import "github.com/astaxie/beego"
// CMS API
type CMSController struct {
beego.Controller
}
func (c *CMSController) URLMapping() {
c.Mapping("StaticBlock", c.StaticBlock)
c.Mapping("Product", c.Product)
}
// @Title getStaticBlock
// @Description get all the staticblock by key
// @Param key path string true "The email for login"
// @Success 200 {object} models.ZDTCustomer.Customer
// @Failure 400 Invalid email supplied
// @Failure 404 User not found
// @router /staticblock/:key [get]
func (c *CMSController) StaticBlock() {
}
// @Title Get Product list
// @Description Get Product list by some info
// @Success 200 {object} models.ZDTProduct.ProductList
// @Param category_id query int false "category id"
// @Param brand_id query int false "brand id"
// @Param query query string false "query of search"
// @Param segment query string false "segment"
// @Param sort query string false "sort option"
// @Param dir query string false "direction asc or desc"
// @Param offset query int false "offset"
// @Param limit query int false "count limit"
// @Param price query float false "price"
// @Param special_price query bool false "whether this is special price"
// @Param size query string false "size filter"
// @Param color query string false "color filter"
// @Param format query bool false "choose return format"
// @Failure 400 no enough input
// @Failure 500 get products common error
// @router /products [get]
func (c *CMSController) Product() {
}
```
首先是CMSController定義上面的注釋,這個是用來顯示這個模塊的作用。接下來就是每一個函數上面的注釋,這里列出來支持的各種注釋:
- @Title
這個API所表達的含義,是一個文本,空格之后的內容全部解析為title
- @Description
這個API詳細的描述,是一個文本,空格之后的內容全部解析為 Description
- @Param
參數,表示需要傳遞到服務器端的參數,有五列參數,使用空格或者tab分割,五個分別表示的含義如下
1. 參數名
2. 參數類型,可以有的值是form、query、path、body、header,form表示是post請求的數據,query表示帶在url之后的參數,path表示請求路徑上得參數,例如上面例子里面的key,body表示是一個raw數據請求,header表示帶在header信息中得參數。
3. 參數類型
4. 是否必須
5. 注釋
- @Success
成功返回給客戶端的信息,三個參數,第一個是status code。第二個參數是返回的類型,必須使用{}包含,第三個是返回的對象或者字符串信息,如果是{object}類型,那么bee工具在生成docs的時候會掃描對應的對象,這里填寫的是想對你項目的目錄名和對象,例如`models.ZDTProduct.ProductList`就表示`/models/ZDTProduct`目錄下的`ProductList`對象。
>>>三個參數必須通過空格分隔
- @Failure
失敗返回的信息,包含兩個參數,使用空格分隔,第一個表示status code,第二個表示錯誤信息
- @router
路由信息,包含兩個參數,使用空格分隔,第一個是請求的路由地址,支持正則和自定義路由,和之前的路由規則一樣,第二個參數是支持的請求方法,放在`[]`之中,如果有多個方法,那么使用`,`分隔。
## 如何自動化生成文檔
要是的文檔工作,你需要做幾個事情,
- 第一開啟應用內文檔開關,在配置文件中設置:`EnableDocs = true`,
- 然后在你的`main.go`函數中引入`_ "beeapi/docs"`。
- 這樣你就已經內置了docs在你的API應用中,然后你就使用`bee run -gendoc=true -downdoc=true`,讓我們的API應用跑起來,`-gendoc=true`表示每次自動化的build文檔,`-downdoc=true`就會自動的下載swagger文檔查看器
好了,現在打開你的瀏覽器查看一下效果,是不是已經完美了。下面是我的API文檔效果:


## 可能遇到的問題
1. CORS
兩種解決方案:
- 把swagger集成到應用中,下載請到[swagger](https://github.com/beego/swagger/releases),然后放在項目目錄下:
if beego.BConfig.RunMode == "dev" {
beego.BConfig.WebConfig.DirectoryIndex = true
beego.BConfig.WebConfig.StaticDir["/swagger"] = "swagger"
}
- API增加CORS支持
ctx.Output.Header("Access-Control-Allow-Origin", "*")
2. 未知錯誤,因為這是我自己項目中使用的,所以可能大家在寫的過程中會遇到一些莫名的錯誤,請提issue去吧!
- 寫在前面的話
- 第0章 beego 簡介
- 0.1 為beego貢獻
- 0.2 發布版本
- 0.3 升級指南
- 第1章 安裝升級
- 1.1 bee工具的使用
- 第2章 快速入門
- 2.1 新建項目
- 2.2 路由設置
- 2.3 Controller運行機制
- 2.4 Model邏輯
- 2.5 View編寫
- 2.6 靜態文件處理
- 第3章 beego的MVC架構
- 3.1 Model設計
- 3.1.1 概述
- 3.1.2 ORM使用
- 3.1.3 CRUD操作
- 3.1.4 高級查詢
- 3.1.5 原生SQL查詢
- 3.1.6 構造查詢
- 3.1.7 事物處理
- 3.1.8 模型定義
- 3.1.9 命令模式
- 3.1.10 測試用例
- 3.1.11 自定義字段
- 3.1.12 FAQ
- 3.2 View設計
- 3.2.1 模板語法指南
- 3.2.2 模板處理
- 3.2.3 模板函數
- 3.2.4 靜態文件處理
- 3.2.5 模板分頁處理
- 3.3 Controller設計
- 3.3.1 參數配置
- 3.3.2 路由設置
- 3.3.3 控制器函數
- 3.3.4 XSRF過濾
- 3.3.5 請求數據處理
- 3.3.6 session 控制
- 3.3.7 過濾器
- 3.3.8 flash 數據
- 3.3.9 URL構建
- 3.3.10 多種格式數據輸出
- 3.3.11 表單數據驗證
- 3.3.12 錯誤處理
- 3.3.13 日志處理
- 第4章 beego的模塊設計
- 4.1 session 模塊
- 4.2 grace 模塊
- 4.3 cache 模塊
- 4.4 logs 模塊
- 4.5 httplib 模塊
- 4.6 context 模塊
- 4.7 toolbox 模塊
- 4.8 config 模塊
- 4.9 i18n 模塊
- 第5章 beego高級編程
- 5.1 進程內監控
- 5.2 API自動化文檔
- 第6章 應用部署
- 6.1 獨立部署
- 6.2 Supervisor部署
- 6.3 Nginx 部署
- 6.4 Apache 部署
- 第7章 第三方庫
- 第8章 應用例子
- 8.1 在線聊天室
- 8.2 短域名服務
- 8.3 Todo列表
- 第9章 FAQ