如何在 ASP.NET Core 9 加入 Swagger UI 介面

微軟從 ASP.NET Core 9 開始正式支援 OpenAPI 規格，並推出 Microsoft.AspNetCore.OpenApi NuGet 套件，在建立 ASP.NET Core Web API 專案時，預設就會加入可以產生 OpenAI 規格的端點。不過，對許多開發人員來說，常用的 Swagger UI 介面卻不見了。今天這篇文章我就來說說怎樣把 Swagger UI 加回專案中。

A conceptual and abstract wide banner image representing modern API development in ASP.NET Core 9

如果你只是要測試 API 的效果，我其實不再推薦使用 Swagger UI 來測試 API 結果，我們現在都盡量在 Visual Studio 2022 中使用 .http 檔案來測試 API，複雜一點的情境我們就會採用 Postman 來管理與自動化測試，若要瀏覽專案中有哪些 API 端點(Endpoint)，可以使用 Endpoints Explorer (端點總管) 來快速導覽整個專案的 API 清單。

使用 Microsoft.AspNetCore.OpenApi 套件

以下是建立 ASP.NET Core Web API 專案並使用以 Controllers 為主的範例：

dotnet new webapi -n api1 -controllers

建立好專案後，你會在 api1.csproj 專案檔中看到 Microsoft.AspNetCore.OpenApi 套件已經被加入：

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.1" />
  </ItemGroup>

</Project>

接著就可以在 Program.cs 中看到已經加入 OpenAPI 支援：

註冊 DI 的地方
```
builder.Services.AddOpenApi();
```

建立 OpenAPI 規格端點的地方

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

啟動專案並瀏覽 OpenAPI 規格的端點
```
dotnet run
```
然後在瀏覽器中開啟 http://localhost:5000/openapi/v1.json 就可以看到 OpenAPI 規格的 JSON 內容了。

Microsoft.AspNetCore.OpenApi 套件提供了在 ASP.NET Core 中生成 OpenAPI 文件的內建支援。該套件提供以下功能：

支援在執行時生成 OpenAPI 文件並透過應用程式上的端點存取
支援 Transformers API，允許修改生成的文件
支援從單一應用程式生成多個 OpenAPI 文件
利用 System.Text.Json 提供的 JSON Schema 支援
與 Natvie AoT 相容

使用 Swashbuckle.AspNetCore.SwaggerUI 套件

早期的專案範本都會加裝 Swashbuckle.AspNetCore 套件，但這個套件會相依於其他套件，其中包含了 OpenAPI 的規格產生器，也包含了 Swagger UI 介面。不過，我們可以透過安裝 Swashbuckle.AspNetCore.SwaggerUI 套件，來加入 Swagger UI 介面。

dotnet add package Swashbuckle.AspNetCore.SwaggerUI

然後在 Program.cs 加入以下端點即可：

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/openapi/v1.json", "OpenAPI V1");
});

瀏覽器中開啟 http://localhost:5000/swagger/ 就可以看到 Swagger UI 介面了。

使用 Swashbuckle.AspNetCore.ReDoc 套件

我們可以透過安裝 Swashbuckle.AspNetCore.ReDoc 套件，來加入 Redoc 介面。

dotnet add package Swashbuckle.AspNetCore.ReDoc

然後在 Program.cs 加入以下端點即可：

app.UseReDoc(options =>
{
    options.SpecUrl("/openapi/v1.json");
});

瀏覽器中開啟 http://localhost:5000/api-docs/ 就可以看到 Swagger UI 介面了。

使用 Scalar.AspNetCore 套件

Scalar 是一個我最近才發現的好用工具，它提供了一個 Scalar.AspNetCore 套件，可以讓我們在 ASP.NET Core 專案中加入 Scalar API Reference 介面，從 Swagger 檔案生成互動式 API 文件。他們甚至有自己的 swagger-editor 頁面可以測試，此功能也已經整合進 Scalar.AspNetCore 套件中！👍

我們需要先安裝 Scalar.AspNetCore 套件
```
dotnet add package Scalar.AspNetCore
```
然後在 Program.cs 加入以下端點即可：
```
app.MapScalarApiReference();
```
瀏覽器中開啟 http://localhost:5000/scalar/v1 就可以看到 Scalar 的 API 文件畫面了。

我必須說，這套 Scalar 確實比 Swashbuckle.AspNetCore.SwaggerUI 強太多了！👍