四種選擇替換.NET 9 API中的Swagger

設定標準API專案

Tim首先在Visual Studio中建立了一個簡化的API專案，選擇了標準的ASP.NET Core Web 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包 .NET: 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 APIs並顯示結構化文件，ReDoc非常適合。

值得注意的是，ReDoc會根據提供的OpenAPI規範自動生成內容，涵蓋預期的響應、參數和資料型別。這非常適合優先考慮文件內建支援優化而非交互的專案。

選項3：NSwag - 文件+程式碼生成

接下來，Tim深入介紹了NSwag，一個靈活且功能豐富的工具，它不僅僅是文件化API，它還可以生成多種語言的客戶端程式碼，如C#，TypeScript等。 在安裝NSwag.AspNetCore NuGet包之後，他設置了一個類似Swagger的介面，將其映射到同一個JSON端點。

Tim解釋說NSwag支持Swagger規範和OpenAPI標準，允許開發者選擇他們喜歡的格式。 儘管UI看起來與Swagger相似，但真正讓NSwag脫穎而出的是其外部工具庫和高級功能（如自動客戶端建立）。

他指出，NSwag的程式碼生成能力有助於減少手動整合API的工作量，特別是涉及多個服務或工具的專案中。 這是為構建穩健的客戶端-伺服器通信的團隊提供的強大解決方案。

選項4：Scaler - Tim最喜歡的API測試選擇

Tim介紹了Scaler UI，這是他在所有選項中的個人最愛，被描述為Postman和文件在瀏覽器中的結合。 在新增Scaler.AspNetCore包之後，只需一行程式碼（app.MapScalerApiReference()）即可啟用介面。

Scaler支持完全的互動性，包括執行帶查詢參數、標頭和Cookies的請求。 它的特點是實時反饋—立即返回響應時間、標頭和結果負載。

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在其影片中向我們展示的，所需的只是一些包，數行程式碼，以及探索能最好地服務於您的應用程式和團隊的工具的慾望。