Swagger 从 .NET 9 中删除：有哪些替代方案

news2025/3/17 11:07:39

微软已经放弃了对 .NET 9 中 Swagger UI 包 Swashbuckle 的支持。他们声称该项目“不再由社区所有者积极维护”并且“问题尚未得到解决”。

这意味着当您使用 .NET 9 模板创建 Web API 时，您将不再拥有 UI 来测试您的 API 端点。

我们将调查是否可以在 .NET 9 中使用 Swagger UI 以及是否有更好的替代方案。

创建 .NET 项目

无论您使用 Visual Studio 创建 .NET 8 还是 .NET 9 Web API，您都可以选择启用 OpenAPI 支持。

在 Visual Studio 中创建 Web API 并启用 OpenAPI 支持

当你启用它时，它将在Program.cs文件中配置 OpenAPI。但是，取决于你使用的版本，将取决于配置的内容。

.NET 8 中的 Swashbuckle

这会将 Swashbuckle 配置到您的项目中。当您使用开发环境运行应用程序时，它将加载 Swagger UI，您可以在其中测试应用程序中的 API 端点。

在 .NET 8 中，ASP.NET Core Web API 中加载的 Swagger UI

这是通过添加Swashbuckle.AspNetCoreNuGet 包并将以下代码行添加到Program.cs文件来配置的：

// Program.cs
var builder = WebApplication.CreateBuilder(args);

...

// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}

...

app.Run();

.NET 9 的情况截然不同

但是，当你使用 .NET 9 创建 ASP.NET Core Web API 时，它只会添加引用 OpenAPI 的扩展方法：

// Program.cs
var builder = WebApplication.CreateBuilder(args);

...

builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
}

...

app.Run();

没有对 Swagger 的引用，并且 Swagger UI 链接给您 404 Not Found 错误响应。

在 .NET 9 中找不到 Swagger UI

这意味着您无法默认测试 API 端点。唯一添加的是 OpenAPI JSON 文档，您可以从获得 /openapi/v1.json。

在 .NET 9 中创建 Web API 项目时仅添加 OpenAPI 文档

替代方案

随着 Swashbuckle 的消失，您还可以通过哪些其他方式测试应用程序中的 API 端点？

Postman

Postman 是一个很好的选择，因为它可以轻松测试多个环境。由于 .NET 9 Web API 提供了 OpenAPI JSON 文档，我们可以使用该链接在 Postman 中导入端点。

为此，请打开左上角的菜单，然后转到文件和导入。粘贴 OpenAPI JSON 文档中的 URL，即https://localhost:{portnumber}/openapi/v1.json。

当您执行此操作时，它将添加一个集合并保存从 OpenAPI JSON 文档添加的所有 API 端点。

使用 Postman 测试 ASP.NET Core Web API 端点

它还将基本 URL 添加为变量，使在多个环境中测试变得更加容易。{{baseUrl}}测试不同环境时只需更新变量即可。

此外，它还可以阻止您在应用程序中意外暴露 API 端点。

NSwag

如果您想在应用程序内测试 API 端点，则可以使用NSwag。 NSwag 能够像 Swashbuckle 一样提供 Swagger UI，因此您将看到类似的 UI。

首先，您需要将NSwag.AspNetCoreNuGet 包添加到您的应用程序中。之后，您需要UseSwaggerUi在中调用扩展方法Program.cs。但是，您需要指定 OpenAPI JSON 文档的路径，即 openapi/v1.json。请注意，开头没有正斜杠。

// Program.cs
var builder = WebApplication.CreateBuilder(args);

...

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
   app.MapOpenApi();
   app.UseSwaggerUi(options =>
   {
       options.DocumentPath = "openapi/v1.json";
   });
}

...

app.Run();

当您运行应用程序并指向时/swagger，您将看到与 Swashbuckle 非常相似的 Swagger UI。

使用 Swagger UI 在 .NET 9 Web API 中使用 NSwag

此外，NSwag 还提供NSwagStudio，它允许您导入 OpenAPI JSON 文档并从中生成 C# 代码。如果您正在调用外部 API 并需要生成代码来调用它，这将非常有用。

只需添加 Swashbuckle 即可

值得注意的是，Swashbuckle 仍可在 .NET 9 项目中运行，并且您可以轻松配置它。确保将Swashbuckle.AspNetCore NuGet 包添加到您的项目中，然后将 SwaggerUI 配置添加到您的 .NET 9 项目中Program.cs：

// Program.cs
var builder = WebApplication.CreateBuilder(args);

...

builder.Services.AddEndpointsApiExplorer(); // <!-- Add this line
builder.Services.AddSwaggerGen(); // <!-- Add this line

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseSwagger(); // <!-- Add this line
app.UseSwaggerUI(); // <!-- Add this line
}

...

app.Run();

当您运行应用程序并转到时/swagger，它将使用 Swashbuckle 显示原始 Swagger UI，并允许您测试 API 端点。

Scalar：更好的 API 测试体验

但是微软放弃 Swagger UI 是有原因的，如果你使用 Scalar，你可能会看到这一点。Scalar 提供了更好的 UI 设计，它更易于配置，允许你生成代码以使用多种不同的编程语言调用 API 端点，并允许你向请求添加 cookie、标头和查询参数。

使用 Scalar 测试 ASP.NET Core Web API 端点

要配置它，请添加Scalar.AspNetCoreNuGet 包，然后将以下行添加到您的Program.cs文件中：
// Program.cs
var builder = WebApplication.CreateBuilder(args);

...

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
app.MapScalarApiReference(); // <-- Add this line
}

...

app.Run();

/scalar/v1您可以在运行应用程序时查看 Scalar UI 。

它还允许您配置 Scalar UI 的外观和行为，例如更改标题名称、主题以及是否显示侧边栏。

// Program.cs
using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

...

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
   app.MapOpenApi();
   app.MapScalarApiReference(options =>
   {
       options.WithTitle("My API");
       options.WithTheme(ScalarTheme.BluePlanet);
       options.WithSidebar(false);
   });
}

...
app.Run();