黃金俠

Ruby on Rails / Rubygems / Javascript / Git

利用 Swagger 產生互動式 API 文件

| Comments

Swagger 是一套由 HTML + Javascript 撰寫的 REST API 文件的框架。 (core 是以 scala 寫的)

Demo 頁 可了解到 Swagger 不僅僅提供 API 的規格資訊,也提供互動介面讓開發者可以直接輸入參數進行測試。

亦支援 GET & POST 以外的 http method (PUT、DELETE)。

Demo 頁面的 source code 在 Github 上。也可以參考 wordnik 的 官方正式 API 文件

API 文件內容完全是透過 ajax 取得 JSON data 產生的,因此必須提供 server 吐出符合 Swagger 文件中所定義的 JSON 格式,讓前端網頁能夠生成 API 文件的介面。

在 Swagger 文件中所定義的物件有:

  1. doc: 代表整份 API 文件 (規格文件)
  2. resource: API 文件下的分類目錄 (規格文件)
  3. api: 每一條 REST Request (規格文件)
  4. parameter: api 下的每個參數 (規格文件)
  5. model: 自訂的 return data type (規格文件)

鑿於定義相當繁多且複雜,Swagger 本身有提供部分語言的 API 文件生成後台 (Ruby 開發者可選擇 sinatra),讓開發者能夠花最少的時間開始使用 Swagger。

但筆者仍覺得 Swagger 使開發者進入狀況的門檻仍高,因此花了點時間以 rails app 開發 Swagger json data 的管理後台生成 swagger API 文件,提供後台的 web 操作介面來產生 Swagger 的 API 文件。

Github: https://github.com/marsz/swagger-rails
Demo: http://swagger.5fpro.com/

功能特色:

  1. FB 登入/註冊,單一帳號下可建立多筆 doc
  2. 自訂 API 實際測試的目標網域
  3. 可設定獨立網域 (FQDN),若沒有設定系統也會自動產生一組給你用
  4. resource 可排序

讓我們 step by step 來建立 API 文件吧。
範例是小弟在早期自己寫的 API,用來提供台灣縣市鄉鎮的資料庫。

  1. 建立 doc,內容如下:
  2. 建立 doc 後,系統會提供你 API 實測時的網址格式
  3. 建立 resource (圖略), resource 可以用來當做是管理許多 API 的目錄
  4. 建立 api: 選擇 http method 和 path

    若 API 參數在 path 中,可用大括號包起來,必且給予參數名稱
  5. 填寫 return data type,若為某個 model 的 array 可以以圖內的格式表示
  6. api path 內有參數的話,底下的 parameters 也必須增加 parameter typepath 的參數 (如圖),名稱和大括號內對應
  7. 有關 model 的定義,可在 doc 頁找到,這裡的定義與否不會影響文件的正常顯示,有定義的話文件也會顯示出來,內容也就更完整囉
  8. 點擊 doc information 內的連結即可看到結果(http://gaia-doc.5fpro.tw/#!/3/api_6_get_2)
  9. 當然,API 實測要有資料,必須實作 http://gaia.5fpro.tw/cities/1.json 回傳的 JSON data 才行。

目前的 swagger-rails 仍有許多待增加的功能:

  1. 多人協作
  2. 修改記錄
  3. 自訂前端 CSS
  4. 後台介面優化
  5. 100% 實作 Swagger 所有支援的格式

最後附上筆者目前正式對外開放的 API 文件給各位參考:

  1. THEWALL 這牆音樂
  2. 台灣縣市鄉鎮資料庫, 含郵遞區號
  3. 爬蟲系統 (暫不開放申請)

筆者目前透過自己蓋的 swagger-rails 用於內部溝通居多,不論在 mobile app 開發或跨語言的資料傳遞,透過 Swagger 介面的 API 實測功能,使用者很快就可以了解每條 API 的取用方式與資料格式,大大減少了溝通的成本。

Swagger 參考資料:

  1. Swagger Specification
  2. Swagger Downloads
  3. Official Site

Comments