自動產出API文件

第 11 屆 iThome 鐵人賽

DAY 24

Modern Web

BeeGo系列第 24 篇

11th鐵人賽 golang go beego

elleryq

2019-10-03 09:10:01

2024 瀏覽

分享至

在 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)

這樣程式就修改完成了。