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

相关推荐
Cacciatore->2 小时前
Electron 快速上手
javascript·arcgis·electron
vvilkim2 小时前
Electron 进程间通信(IPC)深度优化指南
前端·javascript·electron
某公司摸鱼前端3 小时前
ES13(ES2022)新特性整理
javascript·ecmascript·es13
清幽竹客4 小时前
vue-30(理解 Nuxt.js 目录结构)
前端·javascript·vue.js
weiweiweb8884 小时前
cesium加载Draco几何压缩数据
前端·javascript·vue.js
我不吃饼干9 天前
鸽了六年的某大厂面试题:你会手写一个模板引擎吗?
前端·javascript·面试
我不吃饼干9 天前
鸽了六年的某大厂面试题:手写 Vue 模板编译(解析篇)
前端·javascript·面试
前端fighter9 天前
为什么需要dependencies 与 devDependencies
前端·javascript·面试
满楼、9 天前
el-cascader 设置可以手动输入也可以下拉选择
javascript·vue.js·elementui
嘉琪0019 天前
2025——js 面试题
开发语言·javascript·ecmascript