4個選擇來替代.NET 9 API中的Swagger

設定標準 API 項目

Tim 首先在 Visual Studio 中創建了一個最小的 API 項目，選擇標準的 ASP.NET Core 網頁 API 模板。

他強調需勾選添加 OpenAPI 支持的選項，這保證您的項目包含通過 JSON 文件端點生成必要的 OpenAPI 文件。

項目運行後，Tim 瀏覽至默認的 OpenAPI 文件 URL（例如，/swagger/v1/swagger.json）以查看原始 OpenAPI 規範。 該文件包含關於您的 API 端點的結構化元數據，包括支援的動詞如 GET、POST 和 DELETE。

雖然功能上可用，Tim 注意到查看原始 OpenAPI 文件並不友好。 為了提供更好的網頁文件界面，他接著演示了四個增強開發者和消費者體驗的外部工具。

選擇 1：Swagger UI – 熟悉的體驗

即使不再是默認包含的工具，Swagger UI 仍然是非常流行的工具。 Tim 演示了如何使用必要的 NuGet 套件 dotnet: Swashbuckle.AspNetCore.SwaggerUI 將其帶回。

在新的項目中設置 Swagger UI 後，於 9:43，他使用簡化語法配置中介軟體，並將啟動 URL 設定為 /swagger。 該 UI 提供了一個使用者友好的 API 文件界面，開發者可以在此查看端點、了解請求參數，並在瀏覽器中進行測試。

雖然 Swagger UI 現在是一個外部工具，但它仍然支持 OpenAPI 規範，並且在開發期間的基本文件需求中，仍然是最佳選擇之一。

選擇 2：ReDoc – 清晰的唯讀 API 文件

Tim 的第二個工具是 ReDoc，它將您的 OpenAPI 文件轉換為精緻的唯讀 HTML 網站。在添加 OpenAPI 套件 Swashbuckle.AspNetCore.ReDoc 後，他將文件映射到 /api/docs。

與 Swagger UI 不同，ReDoc 不允許端點測試。 然而，作為適合外部用戶和客戶的網頁文件界面，它表現出色。 如果您專注於定義 REST API 和展示結構化文件，ReDoc 是個很好的選擇。

值得注意的是，ReDoc 基於相應的 OpenAPI 規範自動生成內容，涵蓋了預期的響應、參數和數據類型。這對於優先考慮文件內建支持優化而非交互性的項目非常契合。

選擇 3：NSwag – 文件 + 代碼生成

接下來，Tim 介紹了 NSwag，一個靈活且功能豐富的工具，它不僅可以記錄 API，還能為客戶端生成多種語言的代碼，如 C#、TypeScript 等。 在安裝 NSwag.AspNetCore NuGet 套件後，他設置了類似於 Swagger 的界面，並將其映射到相同的 JSON 端點。

Tim 解釋說，NSwag 支持 Swagger 規範和 OpenAPI 標準，允許開發者選擇他們偏好的格式。 儘管 UI 可能看起來類似於 Swagger，但它是外部工具庫和高級特性（如自動客戶端創建）使得 NSwag 大放異彩。

他指出，NSwag 的代碼生成能力在通過多個服務或外部工具集成時，特別有助於減少手動工作量。 對於構建健壯客戶端-服務器通信的團隊來說，這是一個強大的解決方案。

選擇 4：Scaler – Tim 最愛的 API 測試工具

Tim 介紹了 Scaler UI，認為它個人最喜愛的選擇之一，描述它為瀏覽器中的 Postman 和文檔的結合。 在添加 Scaler.AspNetCore 套件後，只需一行代碼（app.MapScalerApiReference()）即可啟用界面。

Scaler 支持完整的互動性，包括執行具有查詢參數、標頭和 Cookie 的請求。 它的獨特之處在於實時反饋——即時返回響應時間、標頭和結果負載。

Scaler 的一大亮點是能夠生成不同語言（例如 PHP、Node、Python、C# 通過 HttpClient 和 RestSharp）的 cURL 命令和客戶端代碼片段。 Tim 發現這對於開發過程中快速複製和貼上 API 調用特別有用。

Scaler 還允許切換輕便和黑暗模式，做為一個用戶友好的 API 文件平台，且有進一步改進的空間。 作為一個開源的 API 平台，Scaler 隨著積極的維護和社群的濃厚興趣而持續發展。

總結：選擇帶來靈活性

在影片的結尾，Tim 強調移除 .NET 網頁模板中的 Swagger UI 可能看似是一種倒退，但事實上是擁抱現代、更量身定制解決方案的機會。 這一變化符合 Microsoft 快速發布周期的節奏，功能變得更加模塊化和專注。

OpenAPI 的支持現在更多地作為一個一等公民的支持而不是一種僵硬、原生的實施方式。 您可以根據項目的需求自由混合搭配工具——不論是使用 Scaler 進行互動測試、使用 NSwag 生成客戶端代碼，或是用 ReDoc 生成清晰的輸出。

Tim 鼓勵開發者探索這些工具，看看哪一個符合他們的工作流程，甚至可以在不同的環境中使用多個 UI（例如，開發時使用一個，公共文件時用另一個）。 這些選項都支持 OpenAPI 和 Swagger 規範，這意味著您不會被鎖定在單一供應商或工作流程。

結論

因為在 .NET 9 中不再默認包含 Swagger UI，開發者現在有選擇最符合 OpenAPI 文檔需求的工具的自由。 不論您是在記錄 HTTP API、服務外部工具，或是支持內部開發，都有符合您目標的解決方案。

有了像 Swagger UI、ReDoc、NSwag 和 Scaler 這樣的工具，記錄和測試 API 從未如此自訂化和開發者友好。 如同 Tim Corey 在他 影片中所展示的，只需要幾個包、一兩行代碼以及探索最適合您的應用和團隊的工具的願望。