API 規格文件：簡單快速設計工具
使用快速規劃 API 規格文件的好處是，它可以幫助開發團隊更有效地溝通和協作。透過清晰的 API 規格文件，團隊成員可以快速了解 API 的功能、輸入和輸出，並且可以更容易地進行開發和測試。此外，API 規格文件還可以提供給其他團隊或合作夥伴，以便他們能夠更好地理解和使用你的 API。
Swagger
在我的 .NET Core 專案中，我常使用 Swagger 來產生 API 文件。然而，在開發階段之前，我們通常無法透過程式碼來產生這些文件。我發現大多數人會使用 Word 或相關的工具來產生這些文件，但我覺得使用 Word 並不是很方便，尤其是當需要產生 JSON 屬性內容時。如果我們等到後端開發完成後才開始產生這些文件，那麼前端或 APP 的開發可能就無法立即開始，這對後端開發者來說是一種巨大的壓力。最近，我開始思考是否可以使用 Markdown 來撰寫這些文件，並且我發現，Markdown 確實是一種非常適合規劃 API 文件的工具。
API Blueprint
API Blueprint 專為 Web API 設計和文檔撰寫。它提供了一種用 Markdown 的方式來描述你的 Web API。
缺點
儘管 API Blueprint 有許多優點，但它在 VSCode 的支援性並不好。許多 VSCode 的 API Blueprint 插件幾乎沒有在維護，這可能會導致一些問題，例如語法高亮顯示不正確或者自動完成功能不穩定。目前還不清楚大家是否已經轉向使用其他的工具，或者他們是如何解決這個問題的。
RAML
RAML 允許我們使用 YAML 編寫 API 文件，這看起來很美好。雖然 Swagger 也可以使用 JSON 來編寫文件，但我更喜歡使用更靈活的方式來撰寫，因此我選擇了 API Blueprint（Markdown）。由於 YAML 支援 schema 驗證，我認為使用 YAML 來編寫 schema 會更好。
API Blueprint 和 RAML 怎麼沒再更新?
VSCode 的支援性並不好，許多 API Blueprint 和 RAML 的插件幾乎都沒有在維護。然而，並沒有明確的說明大家都轉向使用哪種工具。如上所述，許多插件已經有 4 年沒有更新了。後來我在網路上查找資訊時，我發現大家似乎都轉向使用 OpenAPI 了。
看來我需要從 API Blueprint 轉換到 OpenAPI ORZ
OpenAPI
在這篇文章 OpenAPI 打通前後端任督二脈 | 六小編 Editor Leon 中，我了解到 OpenAPI。
至今我們已經看過兩種 API 資訊交換格式 API Blueprint 與 OpenAPI，當然老外一向是造輪子在行的，還有其他的流派像是 RAML、AsyncAPI、AML / AMF 等，目前看來 OpenAPI 已經是最常見的標準，其他流派也或多或少的往與 OpenAPI 相容的方向走，但唯一也是最大的例外是 GraphQL，相較於走 RESTful，以有固定的 schema 的 resource 為基礎的 OpenAPI，GraphQL 則是一種 Query Language，不存在固定的 schema，而是依查詢動態的回覆，兩種標準間很難做到不打折的轉換。
OpenAPI.Tools
OpenAPI-Specification/IMPLEMENTATIONS.md at main · OAI/OpenAPI-Specification
最後，我在 “OAS 版本也許有一些還在用 API Blueprint 或者是 S…” :: SayIt 這篇文章中看到，OpenAPI 似乎比較主流。更多會議內容可以看: View Section: 2017-06-23 「共通性應用程式介面規範」說明會 :: SayIt
它產生的程式碼其實是跨語言的，並沒有特別挑語言，當初為何會挑 OAS？就是因為之前兩個主要描述 API 的文件，一個叫做 Swagger、一個叫做 API Blueprint，這兩家願意合併成 OAS，也就是說基本上 toolkit 的支援、所有的大廠，會發現絕大部分的大廠都在上面，所以本來他們自己就在他們的開發文件裡面，會提供從 OAS 轉到不管是測試用的…… 按圖施工會有一個機器人幫你確保說你說入口的地方都進得去，出口的地方都出得來，這種測試的東西。
看來 OpenAPI 可能是我需要學習的重點。難怪近年來 RAML 和 API Blueprint 都沒有相關工具更新，也沒有人討論。我原本以為這麼好用的工具怎麼沒人用，看來大家都轉向使用 OpenAPI 了。
共通性應用程式介面規範_20170724 - Google 簡報
結論
假如你回 Markdown 就使用 API Blueprint，覺得 YAML 看起來比較舒服，可以使用 RAML。 你可以用用看 OpenAPI，或者選其他工具轉 OpenAPI 都可以。OpenAPI 工具也比較多。
其他文章
Open API UI Framework 介紹：Swagger 與 ReDoc | Greddy’s Blogs