悠悠楠杉
网站页面
在.NET9中采用Scalar替代Swagger：实践与优势解析
07/02
1. 引言
在.NET 开发环境中，Swagger一直是生成和查看RESTful API文档的流行选择，它提供了丰富的API探索和测试功能。然而，随着.NET 9的推出，Microsoft 宣布了Scalar作为Swagger的官方替代品，旨在为开发者提供一种更现代、更高效的方式来管理和生成API文档。
2. Scalar简介
2.1 定义与功能
Scalar是一个轻量级、高度可定制的API文档工具，旨在为.NET开发者提供更灵活的文档生成和集成体验。它支持OpenAPI规范，能够自动从.NET应用中提取路由和模型信息，并生成相应的文档。此外，Scalar集成了对Swagger UI和ReDoc的支持，使得用户可以通过现代界面浏览API文档。
2.2 安装与配置
在.NET 9项目中，可以通过NuGet包管理器轻松安装Scalar。以下是一个基本的安装命令示例：
bash
dotnet add package Microsoft.OpenApi.Extensions --version <latest_version>
安装后，你需要在项目启动配置中启用Scalar：
```csharp
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>()
.ConfigureKestrel(serverOptions =>
{
// 配置Kestrel服务器选项（如端口）
})
.ConfigureEndpointsOptions(options => options.AddScalar()); // 启用Scalar
});
}
```
3. 使用Scalar生成文档
3.1 自动文档生成
Scalar能够自动从你的控制器和模型中提取信息，并生成相应的API文档。例如，对于一个简单的天气API控制器：
csharp
[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
[HttpGet]
public IEnumerable<WeatherForecast> Get() => ... // 实现方法体...
}
当访问/swagger/ui/index或/redoc时，你将会看到由Scalar自动生成的文档界面。此外，你还可以通过自定义配置来调整生成的文档细节。
3.2 自定义与扩展
与Swagger相比，Scalar提供了更丰富的自定义选项。你可以通过编辑配置文件或直接在控制器上使用属性来调整文档的各个方面。例如，为API操作添加备注：
csharp
[HttpGet("my-custom-route")]
[ProducesResponseType(typeof(WeatherForecast), 200)] // 指定返回类型和状态码的注释... [SwaggerOperation(Summary = "获取天气预报", Description = "返回给定日期的天气预报", Tags = new[] { "Weather" })] // 使用Scalars的自定义属性... public IEnumerable<WeatherForecast> GetMyCustomRoute() => ... // 实现方法体... } 这样可以为API操作提供更详细的描述和元数据。 4. 优势与比较 4.1 更轻量级 Scalar 的核心是一个较小的库，相比于 Swagger，它具有更低的内存占用和更快的响应时间。这为高流量项目提供了更好的性能表现。 4.2 更紧密的 .NET 集成 Scalar 是专门为 .NET 设计...
