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

微軟從 ASP.NET Core 9 開始正式支援 [OpenAPI](https://www.openapis.org/) 規格，並推出 [Microsoft.AspNetCore.OpenApi](https://www.nuget.org/packages/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](https://stwillblogassets.blob.core.windows.net/files/images/external/stwillblogassets.blob.core.windows.net/18b18c356682719c40a8-0a1b2083-9112-4422-9ca7-639b84c28212.webp)

> 如果你只是要測試 API 的效果，我其實不再推薦使用 Swagger UI 來測試 API 結果，我們現在都盡量[在 Visual Studio 2022 中使用 .http 檔案](https://learn.microsoft.com/zh-tw/aspnet/core/test/http-files?WT.mc_id=DT-MVP-4015686)來測試 API，複雜一點的情境我們就會採用 Postman 來管理與自動化測試，若要瀏覽專案中有哪些 API 端點(Endpoint)，可以使用 [Endpoints Explorer](https://www.c-sharpcorner.com/article/endpoints-explorer-in-visual-studio-2022/) (端點總管) 來快速導覽整個專案的 API 清單。

### 使用 Microsoft.AspNetCore.OpenApi 套件

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

```bash
dotnet new webapi -n api1 -controllers
```

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

```xml
<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 支援：

1.  註冊 DI 的地方
    
    ```csharp
    builder.Services.AddOpenApi();
    ```
    
2.  建立 OpenAPI 規格端點的地方
    
    ```csharp
    if (app.Environment.IsDevelopment())
    {
        app.MapOpenApi();
    }
    ```
    
3.  啟動專案並瀏覽 OpenAPI 規格的端點
    
    ```bash
    dotnet run
    ```
    
    然後在瀏覽器中開啟 `http://localhost:5000/openapi/v1.json` 就可以看到 OpenAPI 規格的 JSON 內容了。
    

[Microsoft.AspNetCore.OpenApi](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi) 套件提供了在 ASP.NET Core 中生成 OpenAPI 文件的內建支援。該套件提供以下功能：

-   支援在執行時生成 OpenAPI 文件並透過應用程式上的端點存取
-   支援 [Transformers](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/customize-openapi?WT.mc_id=DT-MVP-4015686) API，允許修改生成的文件
-   支援從單一應用程式生成多個 OpenAPI 文件
-   利用 System.Text.Json 提供的 JSON Schema 支援
-   與 Natvie AoT 相容

### 使用 Swashbuckle.AspNetCore.SwaggerUI 套件

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

```bash
dotnet add package Swashbuckle.AspNetCore.SwaggerUI
```

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

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

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

### 使用 Swashbuckle.AspNetCore.ReDoc 套件

我們可以透過安裝 `Swashbuckle.AspNetCore.ReDoc` 套件，來加入 [Redoc](https://redocly.com/docs/redoc) 介面。

```bash
dotnet add package Swashbuckle.AspNetCore.ReDoc
```

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

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

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

### 使用 Scalar.AspNetCore 套件

[Scalar](https://scalar.com/) 是一個我最近才發現的好用工具，它提供了一個 [Scalar.AspNetCore](https://www.nuget.org/packages/Scalar.AspNetCore) 套件，可以讓我們在 ASP.NET Core 專案中加入 [Scalar API Reference](https://github.com/scalar/scalar/blob/main/packages/api-reference/README.md) 介面，從 Swagger 檔案生成互動式 API 文件。他們甚至有自己的 [swagger-editor](https://docs.scalar.com/swagger-editor) 頁面可以測試，此功能也已經整合進 [Scalar.AspNetCore](https://www.nuget.org/packages/Scalar.AspNetCore) 套件中！👍

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

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

![Image](https://stwillblogassets.blob.core.windows.net/files/images/external/github.com/9dac9fe27fabb9ec97f4-2f889c4b-6bc0-4396-9680-39b6d6279f06.jpg)

![Image](https://stwillblogassets.blob.core.windows.net/files/images/external/github.com/230b74040c3d3bf40c2b-ffeb14d6-e543-4fc8-9eb9-29c4af26a4de.jpg)

![Image](https://stwillblogassets.blob.core.windows.net/files/images/external/github.com/cc560f32264232ca77d4-2ac726a2-5df4-4f97-87cc-ede157f68cb4.jpg)

### 相關連結

-   [OpenAPI support in ASP.NET Core API apps](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/overview?WT.mc_id=DT-MVP-4015686)
-   [Endpoints Explorer in Visual Studio 2022](https://www.c-sharpcorner.com/article/endpoints-explorer-in-visual-studio-2022/)
-   [Web API development in Visual Studio 2022 - Visual Studio Blog](https://devblogs.microsoft.com/visualstudio/web-api-development-in-visual-studio-2022/?WT.mc_id=DT-MVP-4015686#endpoints-explorer)
-   [Scalar - Document, Test & Discover APIs](https://scalar.com/)