Apiary API 規格文件+假接口一次到位

Apiary 是個讓我們撰寫 API 規格的服務,但不僅如此,依照它定義的特有的 Markdown 寫下的 API 規格,它的平台可以同時幫我們產出文件與假資料的接口,本文介紹一下它的一些特色。

費用方案

Apiary 目前有免費與收費的方案,在它的網站上可以查到每個方案的差異,不過必須特別提醒的是,Apiary 已經被甲骨文收購,並併入台灣沒什麼人用的 Oracle Cloud 產品線內,未來會不會依舊保持獨立的服務是有疑問的,另外就是甲骨文一貫的…作風,如果對甲骨文特別有疑慮的請自行斟酌使用。

Apiary

回歸正題,Apiary 解決了我們以往在開發 API 時的痛點:

  • 規格文件先寫出來,但 API 還沒有完工,導致無法測試,只能先略過或是假裝 API 是好的來做測試,簡稱瞎測。
  • API 已經寫了,但沒空寫文件,導致串接參數像秘方一樣只能靠口耳相傳,比較邊緣的同事就難以實做串接,最後因為文件一直與實做脫節,導致產品難以維護。
  • 有 API 也有文件,但不知道為何就是串不起來,不確定 API 寫錯還是文件寫錯,總之難免有錯。

API Blueprint

前面提到過在 Apiary 撰寫文件必須使用特有定義的 Markdown,這種 Markdown 的變體有自己的名字 API Blueprint。

API Blueprint 的語法以 Markdown 為基礎,只是加了一些為 API 文件需求而生的語法格式。

API Blueprint 有兩種型式,一種用於定義資料結構,例:

# Data Structures
## Blog Post (object)
+ id: 42 (number, required)
+ text: Hello World (string)
+ author (Author) - Author of the blog post.

## Author (object)
+ name: Boba Fett
+ email: fett@intergalactic.com

應該可以望文生義。

有了資料結構後,就可以把前面定義的資料結構用於 API 定義文件內,例:

# Blog Posts [/posts]
## Retrieve All Posts [GET]
+ Response 200 (application/json)
    + Attributes (array[Blog Post])

API Blueprint 的語法相較於另一派的 XML 或 JSON 都更簡單。

規格文件與假接口

用 API Blueprint 寫好定義文件後,Apiary 會依照文件內的定義,產生出 API 文件與假接口,具體範例可以參考這份官方範例 Sample API Documentation,裡面所有的 API 接口都是可以被使用的。

其它值得一提的功能

除了文件與接口外,另外值得一提的是 Apiary 支援 GitHub Sync,我們可以把 API 定義文件也放到程式專案資料夾內,享受版控的好處,同時透過 GitHub Sync 的機制,每次提交都會觸發 Apiary 也把發布的規格文件更新,好棒棒。

參考資料