Scalar.AspNetCore.Swashbuckle 深度指南用 OpenAPI Filters 为 Swashbuckle 文档注入 Scalar 扩展【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalarScalar.AspNetCore.Swashbuckle是 Scalar 开源 API 平台中面向 .NET 生态的官方集成包它的核心职责是为Swashbuckle.AspNetCore.SwaggerGen提供一组 OpenAPI Filters把 Scalar 特有的扩展稳定性标记、徽章、代码示例、端点隐藏写入你生成的 OpenAPI 文档中。读完本文你将掌握该包的安装与注册方式、全部扩展能力的用法Minimal API 与 Controller 两种写法、底层过滤器的实现原理以及如何用仓库内现成的测试用例验证输出结果。包定位在不改动业务代码的前提下增强 OpenAPI 文档Scalar 本身是一个开源的 API 平台既提供现代化的 REST API 客户端也提供漂亮的 API References 界面并对 OpenAPI/Swagger 有一流的支持。当你在 ASP.NET Core 应用里使用 Swashbuckle 生成 OpenAPI 文档、再用 Scalar.AspNetCore 渲染 Scalar 的 API Reference 界面时往往会希望文档中携带更多面向阅读者的语义信息——比如某个接口是 experimental 还是 stable、某个接口要打上 New 或 Beta 徽章、某个内部接口不要出现在参考文档里。这些需求正是Scalar.AspNetCore.Swashbuckle包的用武之地。其 README 对包定位的描述非常直接TheScalar.AspNetCore.Swashbucklepackage provides OpenAPI filters forSwashbuckle.AspNetCore.SwaggerGenthat enable Scalar-specific extensions in your OpenAPI document.也就是说该包不改变你的 API 实现而是通过 Swashbuckle 的 Filter 机制在文档生成阶段把 Scalar 扩展写入 OpenAPI 文档。从 Scalar.AspNetCore.Swashbuckle.csproj 可以看到它的依赖面很干净Microsoft.OpenApi、Swashbuckle.AspNetCore.SwaggerGen以及项目内引用Scalar.AspNetCore扩展属性与序列化辅助都来自该包。目标框架为net8.0;net9.0;net10.0适用于当前的 .NET 8/9/10 应用。安装与注册一条扩展方法接入全部 Filters首先通过 NuGet 安装包对应官方文档 openapi-extensions.md 中的说明dotnet add package Scalar.AspNetCore.Swashbuckle然后在 OpenAPI 注册阶段调用AddScalarFilters()扩展方法using Scalar.AspNetCore; var builder WebApplication.CreateBuilder(args); // Swashbuckle.AspNetCore.SwaggerGen builder.Services.AddSwaggerGen(options options.AddScalarFilters()); var app builder.Build(); app.MapOpenApi(); // 或 app.UseSwagger() 等 Swashbuckle 的文档暴露方式 app.Run();AddScalarFilters的实现位于 SwaggerGenOptionsExtensions.cs一次调用共注册了 1 个 DocumentFilter 和 4 个 OperationFilterpublic static SwaggerGenOptions AddScalarFilters(this SwaggerGenOptions options) { options.DocumentFilterExcludeFromApiReferenceDocumentFilter(); options.OperationFilterExcludeFromApiReferenceOperationFilter(); options.OperationFilterStabilityOpenApiOperationFilter(); options.OperationFilterCodeSampleOperationFilter(); options.OperationFilterBadgeOperationFilter(); return options; }各过滤器与对应扩展键的对应关系如下过滤器类型写入的扩展键作用StabilityOpenApiOperationFilterOperationFilterx-scalar-stability标记接口稳定性stable / experimental / deprecatedBadgeOperationFilterOperationFilterx-badges为操作添加视觉徽章CodeSampleOperationFilterOperationFilterx-codeSamples为操作添加自定义代码示例ExcludeFromApiReferenceOperationFilterOperationFilterx-scalar-ignore标记单个操作不出现在 API ReferenceExcludeFromApiReferenceDocumentFilterDocumentFilterx-scalar-ignore提升到 tag 级整组隐藏某个 tag 下的全部操作这些扩展键的常量定义集中在 ExtensionKeys.csScalarIgnore、ScalarStability、CodeSamples、Badges并通过 JsonSerializerHelper.cs 中的源生成序列化上下文以 camelCase 命名、忽略 null 值的方式写入 JSON。标记 API 稳定性x-scalar-stability稳定性信息帮助使用者判断一个接口是否适合投入生产。Scalar 定义了三个稳定性级别见 Stability.cs 与官方文档Stable生产就绪的 API序列化为stableExperimental可能随时变更、不建议生产使用的 API序列化为experimentalDeprecated将在未来版本移除的 API序列化为deprecatedMinimal API 写法app.MapGet(/products, GetProducts).Stable(); app.MapGet(/beta-features, GetBetaFeatures).Experimental(); app.MapGet(/legacy-endpoint, GetLegacyData).Deprecated();Controller 写法[HttpGet] [Stability(Stability.Stable)] public IActionResult GetProducts() Ok();Minimal API 一侧的Stable()/Experimental()/Deprecated()扩展方法定义在 EndpointConventionBuilderExtensions.cs它们内部都通过WithStability往 EndpointMetadata 中写入StabilityAttribute定义见 StabilityAttribute.cs。底层过滤器 StabilityOpenApiOperationFilter.cs 的读取逻辑值得注意// We use LastOrDefault because this allows a specific endpoint to override the stability var stabilityAttribute context.ApiDescription.ActionDescriptor.EndpointMetadata .OfTypeStabilityAttribute() .LastOrDefault();也就是说当你在分组MapGroup级别标记了稳定性、又在具体端点上再次标记时LastOrDefault保证端点级标记覆盖分组级标记。命中后过滤器把稳定性值序列化为x-scalar-stability扩展{ x-scalar-stability: experimental }这一输出被 StabilityFilterTests.cs 以 JSON 全量比对的方式验证测试覆盖了stable、experimental、deprecated三种取值。从 API Reference 中隐藏端点x-scalar-ignore有些内部端点你希望保留在 OpenAPI 文档供工具调用中但不想让它在 Scalar 的 API Reference 界面里出现。ExcludeFromApiReference正好解决这个需求且端点仍然可以正常访问。Minimal API 写法app.MapGet(/internal/metrics, GetMetrics).ExcludeFromApiReference();Controller 写法[HttpGet] [ExcludeFromApiReference] public IActionResult GetInternalMetrics() Ok();隐藏逻辑由两个过滤器协作完成ExcludeFromApiReferenceOperationFilter.cs 是 OperationFilter检测到ExcludeFromApiReferenceAttribute后给该操作加上x-scalar-ignore: trueExcludeFromApiReferenceDocumentFilter.cs 是 DocumentFilter它先把文档中所有操作按 tag 分组然后找出该 tag 下全部操作都带x-scalar-ignore的 tag把忽略标记提升到 tag 级别并移除操作上的冗余标记var tagsToExclude tagOperations.Where(kvp kvp.Value.All(operation operation.Extensions is not null operation.Extensions.ContainsKey(ScalarIgnore)));这样处理的好处是Scalar 渲染时只需要识别 tag 级标记即可整组隐藏文档结构也更干净。注意官方文档明确提示——被隐藏的端点仍然可以通过 API 访问只是不会出现在 API Reference 界面中。添加自定义代码示例x-codeSamples默认情况下Scalar 的 API Reference 会为每个操作自动生成多种语言的代码示例。如果你希望针对某个端点提供手写示例例如展示特定的鉴权头、特定的调用方式可以用CodeSample覆盖或补充。Minimal API 写法app.MapPost(/orders, CreateOrder) .CodeSample(fetch(/orders, { method: POST, body: JSON.stringify(order) }), ScalarTarget.JavaScript, Create Order) .CodeSample(curl -X POST /orders -d order.json, ScalarTarget.Shell, Create with cURL);Controller 写法[HttpGet] [CodeSample(fetch(/products).then(r r.json()), ScalarTarget.JavaScript)] public IActionResult GetProducts() Ok();CodeSampleAttribute见 CodeSampleAttribute.cs有三个构造参数sample示例代码内容、languageScalarTarget枚举如ScalarTarget.CSharp、ScalarTarget.JavaScript、ScalarTarget.Shell、label可选标签并且AllowMultiple true一个端点可以挂多个示例。Minimal API 侧对应的扩展方法是 EndpointConventionBuilderExtensions.cs 中的CodeSample。CodeSampleOperationFilter.cs 会把端点元数据中的所有CodeSampleAttribute批量收集为CodeSample数据模型写入x-codeSamples扩展{ x-codeSamples: [ { source: fetch(/orders, { method: POST, body: JSON.stringify(order) }), label: Create Order, language: javascript } ] }添加视觉徽章x-badges徽章用于在 API Reference 界面上给操作附加醒目的视觉标识比如 New、Beta、Internal。每个操作可以挂多个徽章并分别配置位置与颜色。Minimal API 写法app.MapGet(/alpha-feature, GetAlphaFeature) .WithBadge(Alpha) .WithBadge(Beta, BadgePosition.Before) .WithBadge(Internal, BadgePosition.After, #ff6b35); app.MapPost(/orders, CreateOrder) .WithBadge(New, color: #28a745) .WithBadge(Premium, BadgePosition.Before, #ffc107);Controller 写法[HttpGet] [Badge(New)] [Badge(V2, BadgePosition.After, #007bff)] public IActionResult GetExperimentalFeature() Ok();徽章的可配置项官方文档 openapi-extensions.md 与 BadgeAttribute.cs 均有说明参数必填说明name是徽章上显示的文本position否徽章相对操作标题的位置BadgePosition.After默认/BadgePosition.Beforecolor否徽章颜色支持任意 CSS 颜色格式hex、rgb、颜色关键字等BadgePosition枚举定义在 BadgePosition.cs序列化时分别输出为after/before。BadgeOperationFilter.cs 会收集端点上的全部BadgeAttribute同样AllowMultiple true写入x-badges扩展。仓库测试 BadgeFilterTests.cs 给出了非常直观的期望输出——当分组级挂了 Alpha 徽章、端点级又挂了 Betabefore、Gammaafter 颜色、Delta仅颜色时生成的 JSON 为x-badges: [ { name: Alpha }, { name: Beta, position: before }, { name: Gamma, position: after, color: #ffcc00 }, { name: Delta, color: #00ff00 } ]可见分组级徽章会自动继承到组内每个操作上这也是为什么一个操作可能同时包含来自分组和自身两部分的徽章。已弃用端点的处理除了x-scalar-stability: deprecated这种标记方式仓库中还提供了一个专门处理DeprecatedAttribute的过滤器 DeprecatedEndpointFilter.cs。它读取Scalar.AspNetCore.Attributes.DeprecatedAttribute见 DeprecatedAttribute.cs可传入可选参数reason说明弃用原因或新接口指引然后将operation.Deprecated置为true对应 OpenAPI 标准的deprecated字段若提供了reason则把它追加到操作的Description中。需要说明的是从源码结构看AddScalarFilters当前并未注册该过滤器仓库中已注册的是稳定性、徽章、代码示例和隐藏端点这五个过滤器。如果你希望启用原因描述式的弃用标注可以按需自行通过options.OperationFilter...()注册或优先使用[Stability(Stability.Deprecated)]/.Deprecated()的稳定性路径。底层实现剖析一套统一的元数据读取模式把五个过滤器放在一起看会发现它们遵循完全一致的实现模式这也是本包易于理解和扩展的原因从 EndpointMetadata 读取特性所有过滤器都通过context.ApiDescription.ActionDescriptor.EndpointMetadata.OfTypeTAttribute()从端点元数据中取出对应特性——Minimal API 的.WithBadge(...)/.CodeSample(...)扩展方法最终调用builder.WithMetadata(new XxxAttribute(...))见 EndpointConventionBuilderExtensions.csController 则直接使用[Xxx]特性两条路径殊途同归最终都落在 EndpointMetadata 上按需初始化扩展集合operation.Extensions ?? new Dictionarystring, IOpenApiExtension();确保不覆盖已有扩展幂等写入使用Extensions.TryAdd(...)避免重复注入同一个扩展键统一序列化JsonSerializerHelper.cs 使用System.Text.Json的源生成上下文ScalarExtensionsSerializerContext序列化CodeSample、Badge、Stability等模型并统一配置 camelCase 命名与 null 值忽略保证输出的扩展 JSON 风格一致。这种特性Attribute声明 Filter 消费的设计让所有扩展能力都可以同时工作在 Minimal API、Controller 与最小化 API 的各种托管模型上且不需要修改任何业务实现代码。测试与验证仓库如何保证扩展输出正确Scalar.AspNetCore.Swashbuckle的每个过滤器都有对应的集成测试位于 integrations/dotnet/aspnetcore/tests/Scalar.AspNetCore.Swashbuckle.Tests包括BadgeFilterTests.cs验证x-badges的完整 JSON 结构StabilityFilterTests.cs验证x-scalar-stability三种取值CodeSampleFilterTests.cs验证x-codeSamples的注入ExcludeFromApiReferenceFilterTests.cs验证x-scalar-ignore的隐藏逻辑。测试的写法很有参考价值它们通过WebApplicationFactoryConfigureTestServices注册AddScalarFilters动态搭建路由含MapSwagger、MapGroup、端点级与分组级的特性组合再请求生成的 OpenAPI JSON 与期望输出做全量匹配。如果你在自己的项目中接入本包完全可以把这些测试当作行为契约快速确认扩展输出的精确格式。快速上手参考一个完整的 Minimal API 接入示例综合了分组级与端点级扩展参考仓库 playground 的 BookEndpoints.cs 与 Program.csusing Scalar.AspNetCore; var builder WebApplication.CreateBuilder(args); builder.Services.AddSwaggerGen(options options.AddScalarFilters()); builder.Services.AddOpenApi(); var app builder.Build(); app.MapOpenApi(); app.MapScalarApiReference(); // 挂载 Scalar API Reference 界面 var books app.MapGroup(/books).WithTags(bookstore); books.MapGet(/, () Results.Ok()).Stable(); books.MapGet(/{id}, (Guid id) Results.Ok()).Experimental() .WithBadge(Beta, BadgePosition.Before, #ffcc00); books.MapDelete(/{id}, (Guid id) Results.NoContent()) .WithBadge(Caution, BadgePosition.Before, #ffc2c2); app.Run();至此你的 Swashbuckle 文档中就会自动携带x-scalar-stability、x-badges、x-codeSamples、x-scalar-ignore等 Scalar 扩展Scalar API Reference 界面将据此渲染出带稳定性标识、徽章、自定义代码示例且过滤掉内部端点的文档体验。想要进一步查阅各扩展的完整能力与属性说明可以对照 openapi-extensions.md 文档并结合本文提到的过滤器源码逐一验证。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Scalar.AspNetCore.Swashbuckle 深度指南用 OpenAPI Filters 为 Swashbuckle 文档注入 Scalar 扩展【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalarScalar.AspNetCore.Swashbuckle是 Scalar 开源 API 平台中面向 .NET 生态的官方集成包它的核心职责是为Swashbuckle.AspNetCore.SwaggerGen提供一组 OpenAPI Filters把 Scalar 特有的扩展稳定性标记、徽章、代码示例、端点隐藏写入你生成的 OpenAPI 文档中。读完本文你将掌握该包的安装与注册方式、全部扩展能力的用法Minimal API 与 Controller 两种写法、底层过滤器的实现原理以及如何用仓库内现成的测试用例验证输出结果。包定位在不改动业务代码的前提下增强 OpenAPI 文档Scalar 本身是一个开源的 API 平台既提供现代化的 REST API 客户端也提供漂亮的 API References 界面并对 OpenAPI/Swagger 有一流的支持。当你在 ASP.NET Core 应用里使用 Swashbuckle 生成 OpenAPI 文档、再用 Scalar.AspNetCore 渲染 Scalar 的 API Reference 界面时往往会希望文档中携带更多面向阅读者的语义信息——比如某个接口是 experimental 还是 stable、某个接口要打上 New 或 Beta 徽章、某个内部接口不要出现在参考文档里。这些需求正是Scalar.AspNetCore.Swashbuckle包的用武之地。其 README 对包定位的描述非常直接TheScalar.AspNetCore.Swashbucklepackage provides OpenAPI filters forSwashbuckle.AspNetCore.SwaggerGenthat enable Scalar-specific extensions in your OpenAPI document.也就是说该包不改变你的 API 实现而是通过 Swashbuckle 的 Filter 机制在文档生成阶段把 Scalar 扩展写入 OpenAPI 文档。从 Scalar.AspNetCore.Swashbuckle.csproj 可以看到它的依赖面很干净Microsoft.OpenApi、Swashbuckle.AspNetCore.SwaggerGen以及项目内引用Scalar.AspNetCore扩展属性与序列化辅助都来自该包。目标框架为net8.0;net9.0;net10.0适用于当前的 .NET 8/9/10 应用。安装与注册一条扩展方法接入全部 Filters首先通过 NuGet 安装包对应官方文档 openapi-extensions.md 中的说明dotnet add package Scalar.AspNetCore.Swashbuckle然后在 OpenAPI 注册阶段调用AddScalarFilters()扩展方法using Scalar.AspNetCore; var builder WebApplication.CreateBuilder(args); // Swashbuckle.AspNetCore.SwaggerGen builder.Services.AddSwaggerGen(options options.AddScalarFilters()); var app builder.Build(); app.MapOpenApi(); // 或 app.UseSwagger() 等 Swashbuckle 的文档暴露方式 app.Run();AddScalarFilters的实现位于 SwaggerGenOptionsExtensions.cs一次调用共注册了 1 个 DocumentFilter 和 4 个 OperationFilterpublic static SwaggerGenOptions AddScalarFilters(this SwaggerGenOptions options) { options.DocumentFilterExcludeFromApiReferenceDocumentFilter(); options.OperationFilterExcludeFromApiReferenceOperationFilter(); options.OperationFilterStabilityOpenApiOperationFilter(); options.OperationFilterCodeSampleOperationFilter(); options.OperationFilterBadgeOperationFilter(); return options; }各过滤器与对应扩展键的对应关系如下过滤器类型写入的扩展键作用StabilityOpenApiOperationFilterOperationFilterx-scalar-stability标记接口稳定性stable / experimental / deprecatedBadgeOperationFilterOperationFilterx-badges为操作添加视觉徽章CodeSampleOperationFilterOperationFilterx-codeSamples为操作添加自定义代码示例ExcludeFromApiReferenceOperationFilterOperationFilterx-scalar-ignore标记单个操作不出现在 API ReferenceExcludeFromApiReferenceDocumentFilterDocumentFilterx-scalar-ignore提升到 tag 级整组隐藏某个 tag 下的全部操作这些扩展键的常量定义集中在 ExtensionKeys.csScalarIgnore、ScalarStability、CodeSamples、Badges并通过 JsonSerializerHelper.cs 中的源生成序列化上下文以 camelCase 命名、忽略 null 值的方式写入 JSON。标记 API 稳定性x-scalar-stability稳定性信息帮助使用者判断一个接口是否适合投入生产。Scalar 定义了三个稳定性级别见 Stability.cs 与官方文档Stable生产就绪的 API序列化为stableExperimental可能随时变更、不建议生产使用的 API序列化为experimentalDeprecated将在未来版本移除的 API序列化为deprecatedMinimal API 写法app.MapGet(/products, GetProducts).Stable(); app.MapGet(/beta-features, GetBetaFeatures).Experimental(); app.MapGet(/legacy-endpoint, GetLegacyData).Deprecated();Controller 写法[HttpGet] [Stability(Stability.Stable)] public IActionResult GetProducts() Ok();Minimal API 一侧的Stable()/Experimental()/Deprecated()扩展方法定义在 EndpointConventionBuilderExtensions.cs它们内部都通过WithStability往 EndpointMetadata 中写入StabilityAttribute定义见 StabilityAttribute.cs。底层过滤器 StabilityOpenApiOperationFilter.cs 的读取逻辑值得注意// We use LastOrDefault because this allows a specific endpoint to override the stability var stabilityAttribute context.ApiDescription.ActionDescriptor.EndpointMetadata .OfTypeStabilityAttribute() .LastOrDefault();也就是说当你在分组MapGroup级别标记了稳定性、又在具体端点上再次标记时LastOrDefault保证端点级标记覆盖分组级标记。命中后过滤器把稳定性值序列化为x-scalar-stability扩展{ x-scalar-stability: experimental }这一输出被 StabilityFilterTests.cs 以 JSON 全量比对的方式验证测试覆盖了stable、experimental、deprecated三种取值。从 API Reference 中隐藏端点x-scalar-ignore有些内部端点你希望保留在 OpenAPI 文档供工具调用中但不想让它在 Scalar 的 API Reference 界面里出现。ExcludeFromApiReference正好解决这个需求且端点仍然可以正常访问。Minimal API 写法app.MapGet(/internal/metrics, GetMetrics).ExcludeFromApiReference();Controller 写法[HttpGet] [ExcludeFromApiReference] public IActionResult GetInternalMetrics() Ok();隐藏逻辑由两个过滤器协作完成ExcludeFromApiReferenceOperationFilter.cs 是 OperationFilter检测到ExcludeFromApiReferenceAttribute后给该操作加上x-scalar-ignore: trueExcludeFromApiReferenceDocumentFilter.cs 是 DocumentFilter它先把文档中所有操作按 tag 分组然后找出该 tag 下全部操作都带x-scalar-ignore的 tag把忽略标记提升到 tag 级别并移除操作上的冗余标记var tagsToExclude tagOperations.Where(kvp kvp.Value.All(operation operation.Extensions is not null operation.Extensions.ContainsKey(ScalarIgnore)));这样处理的好处是Scalar 渲染时只需要识别 tag 级标记即可整组隐藏文档结构也更干净。注意官方文档明确提示——被隐藏的端点仍然可以通过 API 访问只是不会出现在 API Reference 界面中。添加自定义代码示例x-codeSamples默认情况下Scalar 的 API Reference 会为每个操作自动生成多种语言的代码示例。如果你希望针对某个端点提供手写示例例如展示特定的鉴权头、特定的调用方式可以用CodeSample覆盖或补充。Minimal API 写法app.MapPost(/orders, CreateOrder) .CodeSample(fetch(/orders, { method: POST, body: JSON.stringify(order) }), ScalarTarget.JavaScript, Create Order) .CodeSample(curl -X POST /orders -d order.json, ScalarTarget.Shell, Create with cURL);Controller 写法[HttpGet] [CodeSample(fetch(/products).then(r r.json()), ScalarTarget.JavaScript)] public IActionResult GetProducts() Ok();CodeSampleAttribute见 CodeSampleAttribute.cs有三个构造参数sample示例代码内容、languageScalarTarget枚举如ScalarTarget.CSharp、ScalarTarget.JavaScript、ScalarTarget.Shell、label可选标签并且AllowMultiple true一个端点可以挂多个示例。Minimal API 侧对应的扩展方法是 EndpointConventionBuilderExtensions.cs 中的CodeSample。CodeSampleOperationFilter.cs 会把端点元数据中的所有CodeSampleAttribute批量收集为CodeSample数据模型写入x-codeSamples扩展{ x-codeSamples: [ { source: fetch(/orders, { method: POST, body: JSON.stringify(order) }), label: Create Order, language: javascript } ] }添加视觉徽章x-badges徽章用于在 API Reference 界面上给操作附加醒目的视觉标识比如 New、Beta、Internal。每个操作可以挂多个徽章并分别配置位置与颜色。Minimal API 写法app.MapGet(/alpha-feature, GetAlphaFeature) .WithBadge(Alpha) .WithBadge(Beta, BadgePosition.Before) .WithBadge(Internal, BadgePosition.After, #ff6b35); app.MapPost(/orders, CreateOrder) .WithBadge(New, color: #28a745) .WithBadge(Premium, BadgePosition.Before, #ffc107);Controller 写法[HttpGet] [Badge(New)] [Badge(V2, BadgePosition.After, #007bff)] public IActionResult GetExperimentalFeature() Ok();徽章的可配置项官方文档 openapi-extensions.md 与 BadgeAttribute.cs 均有说明参数必填说明name是徽章上显示的文本position否徽章相对操作标题的位置BadgePosition.After默认/BadgePosition.Beforecolor否徽章颜色支持任意 CSS 颜色格式hex、rgb、颜色关键字等BadgePosition枚举定义在 BadgePosition.cs序列化时分别输出为after/before。BadgeOperationFilter.cs 会收集端点上的全部BadgeAttribute同样AllowMultiple true写入x-badges扩展。仓库测试 BadgeFilterTests.cs 给出了非常直观的期望输出——当分组级挂了 Alpha 徽章、端点级又挂了 Betabefore、Gammaafter 颜色、Delta仅颜色时生成的 JSON 为x-badges: [ { name: Alpha }, { name: Beta, position: before }, { name: Gamma, position: after, color: #ffcc00 }, { name: Delta, color: #00ff00 } ]可见分组级徽章会自动继承到组内每个操作上这也是为什么一个操作可能同时包含来自分组和自身两部分的徽章。已弃用端点的处理除了x-scalar-stability: deprecated这种标记方式仓库中还提供了一个专门处理DeprecatedAttribute的过滤器 DeprecatedEndpointFilter.cs。它读取Scalar.AspNetCore.Attributes.DeprecatedAttribute见 DeprecatedAttribute.cs可传入可选参数reason说明弃用原因或新接口指引然后将operation.Deprecated置为true对应 OpenAPI 标准的deprecated字段若提供了reason则把它追加到操作的Description中。需要说明的是从源码结构看AddScalarFilters当前并未注册该过滤器仓库中已注册的是稳定性、徽章、代码示例和隐藏端点这五个过滤器。如果你希望启用原因描述式的弃用标注可以按需自行通过options.OperationFilter...()注册或优先使用[Stability(Stability.Deprecated)]/.Deprecated()的稳定性路径。底层实现剖析一套统一的元数据读取模式把五个过滤器放在一起看会发现它们遵循完全一致的实现模式这也是本包易于理解和扩展的原因从 EndpointMetadata 读取特性所有过滤器都通过context.ApiDescription.ActionDescriptor.EndpointMetadata.OfTypeTAttribute()从端点元数据中取出对应特性——Minimal API 的.WithBadge(...)/.CodeSample(...)扩展方法最终调用builder.WithMetadata(new XxxAttribute(...))见 EndpointConventionBuilderExtensions.csController 则直接使用[Xxx]特性两条路径殊途同归最终都落在 EndpointMetadata 上按需初始化扩展集合operation.Extensions ?? new Dictionarystring, IOpenApiExtension();确保不覆盖已有扩展幂等写入使用Extensions.TryAdd(...)避免重复注入同一个扩展键统一序列化JsonSerializerHelper.cs 使用System.Text.Json的源生成上下文ScalarExtensionsSerializerContext序列化CodeSample、Badge、Stability等模型并统一配置 camelCase 命名与 null 值忽略保证输出的扩展 JSON 风格一致。这种特性Attribute声明 Filter 消费的设计让所有扩展能力都可以同时工作在 Minimal API、Controller 与最小化 API 的各种托管模型上且不需要修改任何业务实现代码。测试与验证仓库如何保证扩展输出正确Scalar.AspNetCore.Swashbuckle的每个过滤器都有对应的集成测试位于 integrations/dotnet/aspnetcore/tests/Scalar.AspNetCore.Swashbuckle.Tests包括BadgeFilterTests.cs验证x-badges的完整 JSON 结构StabilityFilterTests.cs验证x-scalar-stability三种取值CodeSampleFilterTests.cs验证x-codeSamples的注入ExcludeFromApiReferenceFilterTests.cs验证x-scalar-ignore的隐藏逻辑。测试的写法很有参考价值它们通过WebApplicationFactoryConfigureTestServices注册AddScalarFilters动态搭建路由含MapSwagger、MapGroup、端点级与分组级的特性组合再请求生成的 OpenAPI JSON 与期望输出做全量匹配。如果你在自己的项目中接入本包完全可以把这些测试当作行为契约快速确认扩展输出的精确格式。快速上手参考一个完整的 Minimal API 接入示例综合了分组级与端点级扩展参考仓库 playground 的 BookEndpoints.cs 与 Program.csusing Scalar.AspNetCore; var builder WebApplication.CreateBuilder(args); builder.Services.AddSwaggerGen(options options.AddScalarFilters()); builder.Services.AddOpenApi(); var app builder.Build(); app.MapOpenApi(); app.MapScalarApiReference(); // 挂载 Scalar API Reference 界面 var books app.MapGroup(/books).WithTags(bookstore); books.MapGet(/, () Results.Ok()).Stable(); books.MapGet(/{id}, (Guid id) Results.Ok()).Experimental() .WithBadge(Beta, BadgePosition.Before, #ffcc00); books.MapDelete(/{id}, (Guid id) Results.NoContent()) .WithBadge(Caution, BadgePosition.Before, #ffc2c2); app.Run();至此你的 Swashbuckle 文档中就会自动携带x-scalar-stability、x-badges、x-codeSamples、x-scalar-ignore等 Scalar 扩展Scalar API Reference 界面将据此渲染出带稳定性标识、徽章、自定义代码示例且过滤掉内部端点的文档体验。想要进一步查阅各扩展的完整能力与属性说明可以对照 openapi-extensions.md 文档并结合本文提到的过滤器源码逐一验证。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
