DEV Community 👩‍💻👨‍💻

Cover image for Apiary API 規格文件+假接口一次到位
Leon
Leon

Posted on • Originally published at editor.leonh.space

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
Enter fullscreen mode Exit fullscreen mode

應該可以望文生義。

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

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

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

規格文件與假接口

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

其它值得一提的功能

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

參考資料

Top comments (0)

Create an Account!

👀 Just want to lurk?

That's fine, you can still create an account and turn on features like 🌚 dark mode.