微软已经放弃了对 .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();
将 Scalar UI 与 BluePlanet 主题结合使用
希望这篇文章对您有所帮助。
如果您喜欢此文章,请收藏、点赞、评论,谢谢,祝您快乐每一天。