在.NET 9中使用Scalar替代Swagger

背景

.NET 9刚刚正式发布了,如果你创建一个空的Asp.Net Core 9.0的Web API项目,启动之后,你会惊讶地发现陪伴你多年的Swagger没有了!——这是因为ASP.NET Core项目组已经将Swashbuckle.AspNetCore从.NET 9里移除了,详情看这里 [github]Announcement: Swashbuckle.AspNetCore is being removed in .NET 9

image

Swagger被移除的原因可以总结为以下几点:

  • Swashbuckle 维护不力:Swashbuckle 项目不再由社区所有者积极维护,存在许多问题未得到解决,并且未发布兼容 .NET 8 的正式版本。

  • 转向 Microsoft.AspNetCore.OpenApi:ASP.NET Core 团队将增强 Microsoft.AspNetCore.OpenApi 的功能,以取代 Swashbuckle 并实现 OpenAPI 文档生成。

  • 已有替代方案:除了 Swashbuckle,还有 NSwag 等其他项目支持 OpenAPI 文档生成和客户端/服务器代码生成,开发者可以根据项目需求选择合适的方案。

  • 增强内置 API 支持:从 ASP.NET Core 3.1 开始,框架已经提供了 ApiExplorer 等元数据支持,结合 Visual Studio 和 Visual Studio Code 对 .http 文件的内置支持,API 测试和调试体验更佳。

  • 推动 OpenAPI 成为核心组件:ASP.NET Core 团队计划在 .NET 9 中进一步提升 OpenAPI 的集成度,将其作为核心组件,专注于生成 JSON 格式的 OpenAPI 文档。

除了上面提到了NSwag,Scalar也是微软官方推荐的Swagger替代品。

Scalar

Scalar 是一个开源的 API 平台, 提供现代化的 REST API 客户端、精美的 API 文档和一流的OpenAPI/Swagger支持,官方几乎支持所有编程语言和平台。
image

Github地址:https://github.com/scalar/scalar

.NET 9集成Scalar

.NET也是Scalar支持的一等公民,集成非常简单,nuget安装Scalar.AspNetCore包

dotnet add package Scalar.AspNetCore

然后只用增加一个代码即可app.MapScalarApiReference()

using Scalar.AspNetCore;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.MapScalarApiReference(); // scalar/v1
app.MapOpenApi();
}
app.MapGet("/", () => "Hello world!");
app.Run();

最后启动项目,打卡scalar/v1这个地址就是Scalar界面。
image

界面非常清爽,使用也很简单,并且支持夜间模式

添加JWT认证

在Scalar添加JWT也很简单,自定义一个BearerSecuritySchemeTransformer类来实现IOpenApiDocumentTransformer接口即可。

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")) {
// Add the security scheme at the document level
var requirements = new Dictionary < string,
OpenApiSecurityScheme > {
["Bearer"] = new OpenApiSecurityScheme {
Type = SecuritySchemeType.Http,
Scheme = "bearer", // "bearer" refers to the header name here
In = ParameterLocation.Header,
BearerFormat = "Json Web Token"
}
};
document.Components ??= new OpenApiComponents();
document.Components.SecuritySchemes = requirements;
// Apply it as a requirement for all operations
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 > ()
});
}
}
}
}

然后注册即可

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

最后

Scalar是一个优秀的Swagger替代品,某些功能比Swagger更强大,微软官方也是推荐大家使用,大家可以去试试。
https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/using-openapi-documents?view=aspnetcore-9.0#use-scalar-for-interactive-api-documentation
image

(完)

posted @   马行空的博客  阅读(6888)  评论(15编辑  收藏  举报
相关博文:
阅读排行:
· DeepSeek “源神”启动!「GitHub 热点速览」
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· C# 集成 DeepSeek 模型实现 AI 私有化(本地部署与 API 调用教程)
· DeepSeek R1 简明指南:架构、训练、本地部署及硬件要求
· NetPad:一个.NET开源、跨平台的C#编辑器
点击右上角即可分享
微信分享提示