在.NET 9中使用Scalar替代Swagger
背景.NET 9刚刚正式发布了，如果你创建一个空的Asp.Net Core 9.0的Web API项目，启动之后，你会惊讶地发现陪伴你多年的Swagger没有了！——这是因为ASP.NET Core项目组已经将Swashbuckle.AspNetCore从.NET 9里移除了，详情看这里 Announcement: Swashbuckle.AspNetCore is being removed in .NET 9
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支持，官方几乎支持所有编程语言和平台。
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界面。
界面非常清爽，使用也很简单，并且支持夜间模式。
添加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 { = 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
（完）
页:
[1]