學習C#

在Linux上新增Swagger UI到.NET Aspire

Tim Corey

7m 24s

透過手動將URL輸入到瀏覽器中測試API端點可以快速檢查狀況，但當您有多個路由且包含不同的HTTP動詞和請求主體時，此方法將無法運作。 Swagger UI為您提供了一個互動式的瀏覽器面板，您可以在其中呼叫每個端點、檢查回應，以及實驗參數，而無需撰寫單獨的客戶端或記住curl標誌。

在他的影片"Adding Swagger UI to .NET Aspire on Linux"中，Tim Corey從上一集的Tiny Ticket專案開始，並在現有的OpenAPI配置上新增Swagger UI。此過程僅需三行程式碼和一個NuGet包。接著他演示了透過Swagger介面調用票務端點，其中包括排除在啟動機器後未啟動的資料庫連接故障。如果您正在構建C# on Linux系列中的API或想快速參考如何在.NET專案中連接Swagger，這篇文章涵蓋了每個步驟。

安裝Swashbuckle NuGet套件

[0:38 - 1:35] Tim在VS Code中開啟Tiny Ticket專案並導航到API服務的Program.cs。 API已經在上一集中有GET /api/tickets端點，但要調用它必須手動構建URL。要新增正確的測試介面，第一步是安裝Swagger UI套件。

右鍵單擊API專案，選擇"新增 NuGet 套件"，然後搜索Swashbuckle.AspNetCore.SwaggerUI。 Tim安裝了最新版本（錄製時為10.1.7）。安裝後，該套件引用會出現在專案檔中。因為專案已經通過預設的Aspire服務配置包括OpenAPI支援，因此不需要其他依賴項。

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

在Program.cs中配置Swagger UI

[1:35 - 3:12] 安裝套件後，配置被放置在Program.cs的開發專用區塊中。專案已經註冊了app.MapOpenApi()，該註冊在運行時生成OpenAPI規範檔案。Swagger UI僅需知道該檔案位於何處以及該怎麼標記端點群組。

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

該SwaggerEndpoint調用指向OpenAPI規範，該規範是.NET自動生成的。第二個參數是顯示名稱，將出現在Swagger UI下拉列表中。 Tim強調，這三行是整個Swagger設置。您可以新增更多配置以自定義UI、分組端點或新增身份驗證標頭，但對於開發測試工具，預設值已足夠。

有一個細節值得注意：自.NET 9開始，新的API專案不再預設包含Swagger。微軟將關注點分開，以OpenAPI作為標準發行，讓開發者選擇他們首選的UI層。 Swagger、Scalar和其他工具都使用相同的OpenAPI規範檔案，因此您不會鎖定在某個特定閱覽器中。

運行並驗證Swagger介面

[3:12 - 6:07] 儲存後，Tim通過運行和除錯面板啟動專案。一旦Aspire儀表板載入並且API服務顯示為已運行，他導航到API的 URL 並在路徑中附加了/swagger。

Swagger UI載入了"Ticket App API v1"標籤並列出了可用的端點。根端點（/api/tickets從資料庫返回票務資料。

Tim點擊根端點上的"嘗試一下"並進行執行。回應收到200狀態和確認資訊。然後他轉到/api/tickets端點並按下執行，這就是故障排除的開始。

第一次嘗試失敗，出現連接錯誤："在建立與SQL伺服器的連接時出現與網路相關的或特定於實例的錯誤。"資料庫容器在重新啟動機器後未啟動。 Tim打開Portainer，找到SQL ServerDocker容器並啟動它。容器初始化完成後，他返回Swagger並再次執行請求。這次，回應返回200，並顯示資料庫中儲存的三個測試票務。

這段過程實際提醒著，真正基礎設施上的整合測試會發現單元測試和虛擬資料無法察覺的問題。資料庫容器未設置為開機自啟，這意味著重新啟動後的第一次API呼叫將失敗，除非您先驗證容器狀態。

接下來會發生什麼：CRUD端點

[6:07 - 7:20] Tim預覽了本系列即將到來的集數。 Tiny Ticket API目前只有spTickets_GetAll儲存過程。資料庫中的剩餘儲存過程（按ID獲取、插入、更新、刪除）每個都需要一個對應的API端點和正確的HTTP動詞：GET 用於檢索，POST 用於建立，PUT 用於更新，DELETE 用於移除。

他指出，每個端點遵循相同的模式，並且易於實施，但即將到來的影片將逐個涵蓋，以便每部分可以獨立參考。將系列劃分為小而專注的集數意味著您可以直接跳轉到所需的端點型別，而不必通過較長的影片尋找。

結論

[7:20 - 7:24] 將Swagger UI新增到Linux上的.NET Aspire專案只需要一個NuGet包和在Program.cs中的三行配置。預設的Aspire服務設置已經生成了OpenAPI規範檔案，因此Swagger只需要指向該檔案和一個顯示名稱。從那裡，API中的每個端點都可以透過瀏覽器測試，而無需構建單獨的客戶端。

Tim在重新啟動後遇到的資料庫連接問題強調了一個實際問題：當您的開發堆棧包括容器時，請先確認它們正在運行，再測試API端點。 Swagger為這種驗證提供了快速反饋迴圈。

**系列導航：**這篇文章是C# on Linux系列中構建Tiny Ticket應用程式的一部分。前一篇：在Linux上設置.NET Aspire。下一篇：新增按ID獲取端點。

範例提示：如果您偏好使用不同於Swagger的OpenAPI閱覽器，可以安裝類似Scalar或RapiDoc的套件，並指向相同的/openapi/v1.json端點。規範文件是UI中立的，因此您可以在不更改API配置的情況下切換閱覽器。

在他的YouTube頻道上觀看完整影片，並在C# on Linux系列中獲得更多有關構建API的見解。