ASP.NET Core 使用 Scalar 產生 OpenAPI 文件(取代 Swagger UI)

昨天在 Github 的 dotnet/aspnetcore 儲存庫中發布了一個公告：
Announcement: Swashbuckle.AspNetCore is being removed in .NET 9 #58103

簡單來說就是從 .NET 5 開始到 .NET 8 內建的 Swagger UI 套件 Swashbuckle.AspNetCore 因為沒有積極維護、有許多未解決的問題，甚至不直接支援 .NET 8 ，所以微軟團隊決定使用自己的 Microsoft.AspNetCore.OpenApi 套件 來產生 OpenAPI 文件。雖然沒有介面，但是還有很多成熟的工具所以大家不必擔心。

雖然在 .NET 9 或以上的 ASP.NET Core 專案中沒有內建 Swashbuckle.AspNetCore 套件，但是當然也可以直接手動把他加回來。不過我們這裡來使用看看也很受歡迎的另一個 OpenAPI 介面工具：Scalar

在 .NET 9 的 ASP.NET Core 專案中預設會有以下程式碼，用來產生 OpenAPI 的 JSON 文件：

    
var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

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

app.MapGet("/", () => "Hello world!");

app.Run();
    

使用瀏覽器開啟以下連結就可以看到： (註： 需要自行替換 PORT)

    
http://localhost:5261/openapi/v1.json
    

Scalar 使用示範

先使用 NuGet 安裝 Scalar.AspNetCore 套件，或是使用 .NET CLI 執行以下指令安裝

	
dotnet add package Scalar.AspNetCore
    

在 Program.cs 中加入以下程式碼以啟用 Scalar ：

    
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

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

app.MapGet("/", () => "Hello world!");

app.Run();
    

使用瀏覽器開啟以下連結就可以看到 Scalar 介面： (註： 需要自行替換 PORT)

    
http://localhost:5261/scalar/
    

如果是在 .NET 8 中，要和 Swagger UI 同時存在，可以使用下面的方式設定：

    
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.MapOpenApi();
    app.MapScalarApiReference(options =>
    {
        options.OpenApiRoutePattern = "swagger/{documentName}/swagger.json";
        options.WithApiKeyAuthentication(_ => { });
    });
}

app.MapGet("/", () => "Hello world!");

app.Run();
    

參考資料：
Microsoft.Learn - Use openAPI documents
nuget.org - Microsoft.AspNetCore.OpenApi
scalar.com
scalar - .NET Integration