当前位置：首页 > article >正文

.NET 9 中的 WebAPI 文档重新添加Swagger或改用Scalar

article 2025/3/31 1:23:41

示例代码：https://download.csdn.net/download/hefeng_aspnet/90408226

随着.NET 9的发布，ASP.NET Core 团队决定删除内置的 Swagger 支持（Swashbuckle），主要原因如下：

1、维护挑战：Swashbuckle 不再积极维护、缺乏更新并且没有 .NET 8 的官方版本。
本机元数据支持：ASP.NET Core 现在包含内置元数据来描述 API，从而减少了对外部工具的需求。
2、专注于 OpenAPI：微软正在增强对 OpenAPI 的原生支持，以Microsoft.AspNetCore.OpenApi提供无缝的文档生成。
3、现代替代品：.http 文件和Visual Studio 中的Endpoints Explorer等工具允许进行测试和探索，而无需依赖第三方包。
4、鼓励创新：默认删除 Swashbuckle 可以鼓励社区驱动的工具更好地满足开发人员的需求。

该项目展示了如何利用现代替代方案来适应这些变化，并提供了实际示例来帮助您入门。

本文和项目包含的内容

为了帮助开发人员过渡到ASP.NET Core 9的新方向，此存储库包含三个示例：

1、使用 .http 文件：一种在Visual Studio和VS Code中测试 API 的轻量级、现代方法。
2、重新添加 Swagger 支持：为那些仍然想使用 Swagger（Swashbuckle）进行 API 文档编写的人提供的示例。
3、介绍 Scalar：Swagger 的强大替代品，具有附加功能、现代 UI 和丰富的 API 探索功能。

使用 .http 文件

.http 文件允许您直接从编辑器定义和测试HTTP 请求，例如带有REST 客户端扩展的Visual Studio Code或Visual Studio。

为什么是.http 文件？

1、轻量、简单、易于阅读。
2、允许快速测试端点。
3、支持Visual Studio Code中的变量和响应重用。

示例：一个简单的 .http 文件

@hostaddress = https://localhost:5555/calculation
@value1 = 20
@value2 = 22

### Add Request
# @name add
POST {{hostaddress}}/add
Content-Type: application/json

{
"value1": {{value1}},
"value2": {{value2}}
}

### Reuse Response
@addresult = {{add.response.body.result}}

POST {{hostaddress}}/add
Content-Type: application/json

{
"value1": {{addresult}},
"value2": {{addresult}}
}

笔记：

在Visual Studio Code中，REST 客户端扩展支持变量和响应重用（例如add.response.body.result）。

在Visual Studio中，响应变量尚不受支持，但您仍然可以执行请求并有效地调试。

Visual Studio 中的示例 UI：

重新添加 Swagger 支持

虽然 Swagger 已从 .NET 9 中删除，但您可以使用 Swashbuckle 轻松地将其添加回来。

添加Swagger的步骤：

安装所需的 NuGet 包：

dotnet add package Microsoft.AspNetCore.OpenApi
dotnet add package Swashbuckle.AspNetCore

更新Program.cs：

builder.Services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo
{
Title = "Sample API",
Version = "v1",
Description = "API to demonstrate Swagger integration."
});
});

// some code

if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}

Swagger UI 预览：

Swagger 提供了一个清晰的界面来探索和测试您的 API 端点。

Scalar 简介：一种现代替代方案

Scalar是一个开源 API 平台，它将 API 文档和测试提升到了一个新的水平。它提供了现代功能、直观的用户体验和时尚的界面（为真正的工程师提供暗黑模式！）。

为什么要使用Scalar？

1、现代 REST 客户端：无缝测试并与 API 交互。
2、漂亮的 API 参考：生成干净、可读的 API 文档。
3、代码生成：使用 25 种以上的语言或框架生成示例。

Scalar示例输出

C# 示例：

using System.Net.Http.Headers;

var client = new HttpClient();
var request = new HttpRequestMessage
{
Method = HttpMethod.Get,
RequestUri = new Uri("https://localhost:5555/api/v1/time"),
};
using (var response = await client.SendAsync(request))
{
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}