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

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

• 安装 Scalar.AspNetCore 包 在项目中安装 Scalar.AspNetCore NuGet 包。可以通过以下命令完成：
  bash复制
  
  1. dotnet add package Scalar.AspNetCore --version 1.2.*

  复制代码
  建议利用版本号中的通配符（如 1.2.*），以便获取最新的功能和修复。
  
• 配置项目 在 Program.cs 文件中，配置 Scalar 和 OpenAPI 服务：
  csharp复制
  
  1. using Scalar.AspNetCore;
  3. var builder = WebApplication.CreateBuilder(args);
  4. builder.Services.AddOpenApi(); // 添加 OpenAPI 服务
  6. var app = builder.Build();
  8. if (app.Environment.IsDevelopment())
  9. {
  10.     app.MapOpenApi(); // 映射 OpenAPI 文档
  11.     app.MapScalarApiReference(); // 映射 Scalar API 参考界面
  12. }
  14. app.Run();

  复制代码
  启动项目后，访问 /scalar/v1 即可检察 Scalar 提供的交互式 API 文档。
  
• 自界说 Scalar 界面 Scalar 提供了丰富的自界说选项，比方修改主题、标题和侧边栏显示等：
  csharp复制
  
  1. app.MapScalarApiReference(options =>
  2. {
  3.     options.WithTitle("My Custom API"); // 设置标题
  4.     options.WithTheme(ScalarTheme.BluePlanet); // 设置主题
  5.     options.WithSidebar(false); // 隐藏侧边栏
  6. });

  复制代码
  这些配置可以让 Scalar 的界面更好地顺应你的项目需求。
  
• 添加认证支持 假如你的 API 需要认证，可以通过实现 IOpenApiDocumentTransformer 接口来添加 JWT 或其他认证方式。比方，添加 JWT 认证的代码如下：
  csharp复制
  
  1. public sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
  2. {
  3.     public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
  4.     {
  5.         var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
  6.         if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
  7.         {
  8.             var requirements = new Dictionary<string, OpenApiSecurityScheme>
  9.             {
  10.                 ["Bearer"] = new OpenApiSecurityScheme
  11.                 {
  12.                     Type = SecuritySchemeType.Http,
  13.                     Scheme = "bearer",
  14.                     In = ParameterLocation.Header,
  15.                     BearerFormat = "Json Web Token"
  16.                 }
  17.             };
  19.             document.Components ??= new OpenApiComponents();
  20.             document.Components.SecuritySchemes = requirements;
  22.             foreach (var operation in document.Paths.Values.SelectMany(path => path.Operations))
  23.             {
  24.                 operation.Value.Security.Add(new OpenApiSecurityRequirement
  25.                 {
  26.                     [new OpenApiSecurityScheme
  27.                     {
  28.                         Reference = new OpenApiReference { Id = "Bearer", Type = ReferenceType.SecurityScheme }
  29.                     }] = Array.Empty<string>()
  30.                 });
  31.             }
  32.         }
  33.     }
  34. }

  复制代码
  然后在 Program.cs 中注册：
  csharp复制
  
  1. builder.Services.AddOpenApi(opt =>
  2. {
  3.     opt.UseTransformer<BearerSecuritySchemeTransformer>();
  4. });

  复制代码

二、Scalar 的上风

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

总结

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

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。