為什麼需要API Document

• 需求來了
• 前後端需要同時開工 後端先寫好API
• 雙方溝通的文件

何謂API Blueprint

特點

• 線上寫API文檔的平台
• 使用Markdown語法撰寫
• 支援團隊協作
• 支援Mock Server 方便前端可以透過Mock Data先做
• 支援版本管理(GitHub)
• 也可以local運行

缺點

• 存檔需手動存擋
• 線上寫文檔UI的反應有點慢
• 沒有所謂的codegen的tool

何謂Swagger

特點

• API的開發工具
• Swagger使用OpenAPI規範， 這個規範由 Linux 基金會主持，是為了建立世界各地共通的 API 規範。
• 使用語法可以用YAML或者JSON
• Swagger延伸出來很多工具，例如：Swagger UI, Swagger Editor, Swagger Codegen, Swagger Hub
• Swagger UI可以拿來自己本地deploy 自己維護API document server
• Swagger Editor 為線上的編輯器
• Swagger Codegen 自動產生Client 跟Server 的code 拿去當作Mock Server也可以
• Swagger Hub 線上文檔平台 提供類似於API Bluepirnt的服務
• Swagger的生態性相對於API Blueprint豐富很多 找解答會比較好找

針對Swagger Hub來說

• UI等操作性比API Blueprint好
• 但免費版的只支持個人 團隊協作需要花錢
• API Blueprint則是團隊開發可以免費 但有限制數量

總結

• 一開始的小團隊可以使用API Blueprint工具 整體來說還是比較輕量化
• 等到前後端都開發成熟後 可以考慮慢慢轉換到Swagger 可控性會更高
• 這次先用API BluePrint示範 有時間就用Swagger改寫

歡迎參觀團隊其他成員的文章~

• 前端工程師一起來種一棵後端技能樹吧！
• 用舒服的姿勢開發 Python Project