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

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

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

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

   bash复制

   dotnet add package Scalar.AspNetCore --version 1.2.*

   建议使用版本号中的通配符（如 1.2.*），以便获取最新的功能和修复。

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 文档。

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

   csharp复制

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

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

4. 添加认证支持 如果你的 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。你可以尝试将其集成到项目中，以提升开发效率和文档质量