.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。你可以尝试将其集成到项目中，以提升开发效率和文档质量