[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去吧！