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

Apiary 是個讓我們撰寫 API 規格的服務，但不僅如此，依照 Apiary 特有的 Markdown 語法寫下的 API 規格文件，Apiary 會根據規格文件幫我們產出文件與假資料的接口，本文介紹一下它的一些特色。

費用方案

在入坑前一定要先了解他的費用，避免愛上後難以自拔。

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 也把發布的規格文件更新，好棒棒。

參考資料

• [apiary][01] 設計 API 時好用的工具 - 讓前後端溝通格式不再卡卡 - 概念介紹篇