API Blueprint 實用工具小記
Contents
如果是幾年前接觸 API 文件工具，API Blueprint 幾乎一定會被拿來和 Swagger、OpenAPI 一起比較。它的語法可讀性不差，對喜歡 markdown 風格的人其實滿友善。不過現在回頭看，工具生態和社群熱度已經明顯往 OpenAPI 靠攏了。
這篇主要不是要推新專案使用 API Blueprint，而是把我當時踩到的工具狀況記下來，順便說明為什麼現在多半會直接選 OpenAPI。
API Blueprint 是什麼
API Blueprint 是一種用文字描述 API 的格式，強調文件可讀性。你可以把它想成「用比較接近 markdown 的方式寫 API 規格」，對簡單文件來說上手不難。
當時遇到的工具問題
1. VS Code Extension 能用，但不夠順
有些 extension 雖然能編輯或預覽，但進階功能常常綁定額外服務或 token。這種情況在小型嘗試還能接受，一旦要放進正式工作流就會變得很卡。
2. 錯誤提示不一定清楚
文件格式只要稍微寫錯，有些 viewer 不會很明確告訴你哪裡出問題，導致除錯效率不高。這在 API 文件工具上其實很傷，因為你會花很多時間在猜語法。
為什麼現在多半改看 OpenAPI
主要原因很實際：
- 工具更多。
- 編輯器支援更成熟。
- 文件產出、Mock、程式碼產生器生態更完整。
- 團隊溝通時更容易找到共通標準。
所以如果是新專案，現在通常不太建議再從 API Blueprint 起步。
既有 Blueprint 文件怎麼辦
如果手上已經有既有文件，也不一定要一次全砍。比較務實的做法是：
- 先維持現況，確保文件還能被閱讀。
- 找工具把 Blueprint 轉成 OpenAPI。
- 後續新功能直接改在 OpenAPI 上維護。
當時有找到一個轉換工具：
這類工具不見得能百分之百無痛轉換，但至少可以當成遷移起點。
小結
API Blueprint 並不是不能用，而是站在現在的時間點來看，生態優勢已經不在它這邊。若是新系統或新團隊，直接選 OpenAPI 通常比較省事；如果是舊專案還留著 Blueprint，則比較適合規劃漸進式遷移，而不是繼續把新文件押在它上面。