.NET 9 微软官方推荐使用 Scalar 替代传统的 Swagger

在 .NET 9 中，微软官方推荐使用 Scalar 替代传统的 Swagger（Swashbuckle）作为 API 文档和交互工具。Scalar 是一个现代化的 API 平台，支持 OpenAPI/Swagger 规范，提供精美的文档界面和强大的功能。

一、如何在 .NET 9 中集成 Scalar

安装 Scalar.AspNetCore 包 在项目中安装 Scalar.AspNetCore NuGet 包。可以通过以下命令完成：

bash复制
```
dotnet add package Scalar.AspNetCore --version 1.2.*
```
建议使用版本号中的通配符（如 1.2.*），以便获取最新的功能和修复。

配置项目 在 Program.cs 文件中，配置 Scalar 和 OpenAPI 服务：

csharp复制

using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi(); // 添加 OpenAPI 服务

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi(); // 映射 OpenAPI 文档
    app.MapScalarApiReference(); // 映射 Scalar API 参考界面
}

app.Run();

启动项目后，访问 /scalar/v1 即可查看 Scalar 提供的交互式 API 文档。

自定义 Scalar 界面 Scalar 提供了丰富的自定义选项，例如修改主题、标题和侧边栏显示等：

csharp复制

app.MapScalarApiReference(options =>
{
    options.WithTitle("My Custom API"); // 设置标题
    options.WithTheme(ScalarTheme.BluePlanet); // 设置主题
    options.WithSidebar(false); // 隐藏侧边栏
});

这些配置可以让 Scalar 的界面更好地适应你的项目需求。

添加认证支持 如果你的 API 需要认证，可以通过实现 IOpenApiDocumentTransformer 接口来添加 JWT 或其他认证方式。例如，添加 JWT 认证的代码如下：

csharp复制

public sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
{
    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
    {
        var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
        if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
        {
            var requirements = new Dictionary<string, OpenApiSecurityScheme>
            {
                ["Bearer"] = new OpenApiSecurityScheme
                {
                    Type = SecuritySchemeType.Http,
                    Scheme = "bearer",
                    In = ParameterLocation.Header,
                    BearerFormat = "Json Web Token"
                }
            };

            document.Components ??= new OpenApiComponents();
            document.Components.SecuritySchemes = requirements;

            foreach (var operation in document.Paths.Values.SelectMany(path => path.Operations))
            {
                operation.Value.Security.Add(new OpenApiSecurityRequirement
                {
                    [new OpenApiSecurityScheme
                    {
                        Reference = new OpenApiReference { Id = "Bearer", Type = ReferenceType.SecurityScheme }
                    }] = Array.Empty<string>()
                });
            }
        }
    }
}

然后在 Program.cs 中注册：

csharp复制

builder.Services.AddOpenApi(opt =>
{
    opt.UseTransformer<BearerSecuritySchemeTransformer>();
});

二、Scalar 的优势

现代化界面：Scalar 提供了更现代、更美观的界面，支持夜间模式。
功能强大：支持多种编程语言的客户端代码生成，并允许在请求中添加 Cookie、头信息和查询参数。
安全性：支持多种认证方式，包括 API Key、OAuth2、HTTP Basic 和 Bearer。

总结

Scalar 是一个优秀的 Swagger 替代品，提供了更强大的功能和更好的用户体验。微软官方也推荐在 .NET 9 中使用 Scalar。你可以尝试将其集成到项目中，以提升开发效率和文档质量