iT邦幫忙

第 11 屆 iT 邦幫忙鐵人賽

DAY 24
0
Modern Web

BeeGo系列 第 24

自動產出API文件

在 Controller 函式加上註解以後,BeeGo 可以自動幫你產出 API 文件,就不需要另外再寫一次文件了。BeeGo 用的是 swagger。

這篇,我們就把之前用 bee 工具產生的 UserController (controllers/user.go) 做成 API。

註解

函式的註解會被萃取出來填到 swagger 文件裡,bee 幫我們產生的 UserController 裡已經帶有所需要的註解了。

這個註解的格式很像 JavaDoc :

  • @Title :名稱
  • @Summary :簡單的說明
  • @Deprecated :是否已經過期
  • @Description :說明
  • @Param :參數,總共有五欄,以空白分隔
    1. 參數名稱
    2. 參數位置,可以填 path, query, formData, body, header 這幾個。
    3. 型態,就 string, int 等等的。
    4. 是否必要,填 true 或 false
    5. 說明
    6. 預設值
  • @Success:成功所回傳的,有3個欄位要填
    1. HTTP 狀態碼,一般填 200
    2. 回傳型態,一定要用 {} 包起來,例如 {object}
    3. 回傳的物件說明或字串,例如 ZDT.ZDTMisc.CmsResponse
  • @Failure:錯誤回傳的,可以有多個。
    1. HTTP 狀態碼
    2. 錯誤訊息
  • @Accept:可接受的 content type,例如 json
  • @router :就 endpoint ,例如:/staticblock/:key [get]

上面是針對函式的,下面則是放在 Controller 檔案前面的:

  • @APIVersion :API 版本
  • @Title :標題、名稱
  • @Description :說明
  • @Contact :聯絡人
  • @TermsOfServiceUrl :服務條款網址
  • @License :授權
  • @LicenseUrl :授權網址
  • @Name :名稱
  • @URL :網址
  • @Host :主機

程式

加好註解以後,要在 main.go 裡加入靜態文件的處理。主要原因是等等我們用 bee run 執行的時候,會產生出 swagger 文件,並且放到 swagger 目錄下,這裏面實際上是一堆 HTML/CSS/JavaScript,所以程式必須要加入 static 目錄的處理。

// 加在 func init() 的最後
beego.SetStaticPath("/swagger", "swagger")

然後要在 router 加入路徑,這路徑必須要先使用 NewNamespace() 生成 namespace 物件,再用 AddNamespace() 加入。

所以開啟 routers/router.go,在 func init() 最後加入以下程式

// Automated API Documentation
    ns := beego.NewNamespace(
        "/v1",
        beego.NSNamespace(
            "/user",
            beego.NSInclude(&controllers.UserController{}),
        ),
    )
    beego.AddNamespace(ns)

這樣程式就修改完成了。

執行

在用 bee run 執行的時候,需要額外加參數

bee run -downdoc=true -gendoc=true

這樣就可以囉,請打開瀏覽器去瀏覽 http://localhost:8080/swagger/ 就可以看到 API 文件了。

然後在網址列輸入 http://localhost/v1/user/ 也可以順利的呼叫 UserController 裡的 GetAll() 來取得 user 資料了。

參考資料


上一篇
回應格式
下一篇
Docker - MultiStage
系列文
BeeGo30

尚未有邦友留言

立即登入留言