revel + swagger 文檔也能互動啦

beego 從 1.3 後開始支持自動化API文檔，不過，目測比較複雜，一直指望 revel 能有官方支持。

revel 確實已經有了官方支持的計劃，有可能將在 0.14 版本支持，如今才 0.11.1 版本，只好本身手工擼一個出來，半自動化，但能知足基本需求了。

1. 準備

1.1 swagger-ui

swagger 是一個開源項目，swagger-ui 將符合 swagger 定義的描述規則的 Json 數據以網頁形式呈現。

swagger 有在線的實例能夠直接看到 swagger-ui 文檔效果，以下：

swagger-ui 自己是不須要依賴任何第三方代碼的，而使用 swagger-ui 實現 revel 的 API 文檔僅需 swagger-ui 源碼 dist 文件夾中的文件，能夠以下獲取：

git clone https://github.com/swagger-api/swagger-ui

而後，將 dist 路徑下文件拷貝到工程目錄（目錄結構見下文）。

1.2 代碼生成

swagger 有專門的代碼生成項目 swagger-codegen，但彆着急，revel 須要的不是它，是在 swagger-spec 發現的 Swagger spec generator，golang 實現、自帶 swagger-ui。

go get github.com/yvasiyarov/swagger

直接命令行輸入swagger 回車

支持三個級別註釋：

• General API info, API 通用信息，在項目入口函數所在文件寫一份便可，例如 init.go

  // @APIVersion 1.0.0
  // @Title My Cool API
  // @Description My API usually works as expected. But sometimes its not true
  // @Contact api@contact.me
  // @TermsOfServiceUrl http://google.com/
  // @License BSD
  // @LicenseUrl http://opensource.org/licenses/BSD-2-Clause

• Sub API Definitions, 子模塊定義，每一個資源定義一次

  // @SubApi Order management API [/order]
  // @SubApi Statistic gathering API [/cache-stats]

• API Operation, API 定義，須要文檔化的接口函數

  // @Title getOrdersByCustomer
  // @Description retrieves orders for given customer defined by customer ID
  // @Accept json
  // @Param customer_id path int true "Customer ID"
  // @Param order_id query int false "Retrieve order with given ID only"
  // @Param order_nr query string false "Retrieve order with given number only"
  // @Param created_from query string false "Date-time string, MySQL format. If specified, API will retrieve orders that were created starting from created_from"
  // @Param created_to query string false "Date-time string, MySQL format. If specified, API will retrieve orders that were created before created_to"
  // @Success 200 {array} my_api.model.OrderRow
  // @Failure 400 {object} my_api.ErrorResponse Customer ID must be specified
  // @Resource /order
  // @Router /orders/by-customer/{customer_id} [get]

1.3 revel module

revel 支持模塊，每一個模塊能夠有獨立的路由和配置文件，即 routes.go 和 app.conf，revel 負責將其與其餘模塊及主應用對應文件合併，詳細規則可參考 revel 文檔相關章節 Modules。

swagger-ui 將以 revel module 方式插入主應用，須要設計獨立的路由。

1.4 目錄結構

revel new revel-swagger

新建 modules 文件夾，並在其中創建 swagger-ui 文件夾，以下：

2 實現

2.1 Step 1

• 複製 yvasiyarov/swagger/swagger-ui/ 路徑下文件至 revel-swagger/modules/swagger/swagger-ui

• 在 revel-swagger/modules/swagger/conf 新建 routes 文件，放入以下路由

  GET /docs Docs.GetApiDocs
  GET /docs/api/*filepath Static.ServeModule("swagger","swagger-ui")
  GET /docs/:apiKey Docs.GetApiDoc

• 在 revel-swagger/modules/swagger/app/controllers 新建 apidocs.go 並實現 routes 中定義的路由

2.2 Step 2

• 在主應用 app.conf 文件中添加模塊引用 module.swagger = you/path/to/revel-swagger/modules/swagger
• 在主應用 routes 文件中添加模塊路由 module:swagger

2.3 Step 3

• 使用 github.com/yvasiyarov/swagger 生成 swagger 支持的 Json 註釋文件 docs.go
  • -apiPackage 設置爲主應用 app/controllers 路徑，路徑爲相對於 $GOPATH/src 的相對路徑
  • -mainApiFile 設置爲主應用的某個 .go 文件路徑，做爲 swagger 通用 API 信息定義文件，一樣路徑爲相對 $GOPATH/src 的路徑
  • -output 輸出路徑，設置爲 you/path/to/revel-swagger/modules/swagger/app/controllers，爲絕對路徑

在 you/path/to/revel-swagger/modules/swagger/app/controllers 生成了 docs.go 文件，此時，訪問 localhost 就能夠看到 swagger-ui 頁面了，不過內容仍是 swagger 的示例。

2.4 Step 4

• init.go 添加 General API info
• app.go 添加 API 接口及註釋
• 修改 swager-ui/index.html 第 28 行爲 url: "http://127.0.0.1:9000/docs"
• 從新生成 docs.go
  • 設置 -basePath=127.0.0.1:9000

訪問 http://127.0.0.1:9000 能夠看到 API 的 swagger 文檔了：

3 其餘

• yvasiyarov/swagger 支持的數據格式須要參考其項目說明
  • 沒有找到 上傳文件及參數爲數組的描述方法，swagger 自己是支持的
• 示例代碼放在 github