.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。你可以尝试将其集成到项目中，以提升开发效率和文档质量
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。
页:
[1]