常见的需求：
一次在 UI 中输入 JWT Token 后，所有“Try it out” 请求自动在 Header 中添加 Authorization: Bearer {your-token}（即“默认添加”）。
核心原理：
在 OpenAPI 文档中注册 Bearer Security Scheme，这样在 Swagger UI / Scalar UI 界面上会自动显示 Authorize 按钮。当我们输入一次 Token 后，UI 就会在后续所有请求中自动带上它（浏览器会话内持久化）。
我们基于你之前的两种方案（或 Scalar）分别给出最简、最推荐的实现（官方 .NET 10 最佳实践，使用 IOpenApiDocumentTransformer）。
以下是配置的最佳实践（IOpenApiDocumentTransformer）
基于Swagger UI
确保你的项目已配置了 JWT 认证
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
.AddJwtBearer(options => {
/* Issuer、Audience、SigningKey 配置 */
});
builder.Services.AddAuthorization();步骤 1：创建 Transformer 类（新建文件 Transformers/BearerSecuritySchemeTransformer.cs）
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi;
using Microsoft.OpenApi.Models;
internal sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider)
: IOpenApiDocumentTransformer
{
public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
{
var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
// 只有启用了 Bearer 认证才添加 Security Scheme
if (authenticationSchemes.Any(authScheme => authScheme.Name == JwtBearerDefaults.AuthenticationScheme))
{
var securitySchemes = new Dictionary<string, IOpenApiSecurityScheme>
{
["Bearer"] = new OpenApiSecurityScheme
{
Type = SecuritySchemeType.Http,
Scheme = "bearer",
In = ParameterLocation.Header,
BearerFormat = "Json Web Token",
Description = "请输入 JWT Token（格式：Bearer eyJ...）"
}
};
document.Components ??= new OpenApiComponents();
document.Components.SecuritySchemes = securitySchemes;
// 可选：全局为所有接口添加安全要求（所有接口默认需要 JWT Token）
// foreach (var path in document.Paths.Values)
// {
// foreach (var operation in path.Operations.Values)
// {
// operation.Security ??= new List<OpenApiSecurityRequirement>();
// operation.Security.Add(new OpenApiSecurityRequirement
// {
// [new OpenApiSecuritySchemeReference("Bearer", document)] = Array.Empty<string>()
// });
// }
// }
}
}
}步骤 2：注册 Transformer（修改 Program.cs）
builder.Services.AddOpenApi(options =>
{
options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
});步骤 3：保持 Swagger UI 配置（已有的代码）
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/openapi/v1.json", "My API v1");
// 可选：美化
// options.DocumentTitle = "我的 WebAPI - JWT 认证";
});
}使用效果：
启动项目 → 打开 /swagger → 右上角出现 Authorize 按钮 → 点击 → 粘贴 Bearer [JWT Token] → 确定。
以后所有接口的 “Try it out” 都会自动带上 Authorization: Bearer … Header。
基于Scalar UI
Scalar 会自动读取 OpenAPI 中的 Security Scheme，配置完全一样！
步骤：
- 使用上面完全相同的 BearerSecuritySchemeTransformer 类（无需额外修改）。
- 在 Program.cs 中注册 Transformer（同上面一样）。
- Scalar 配置保持不变：
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
app.MapScalarApiReference(options =>
{
options
.WithTitle("My API")
.WithTheme(ScalarTheme.Kepler)
.WithDarkModeToggle(true);
// Scalar 自动支持 Bearer Token 输入，无需额外配置
});
}使用效果：
访问 /scalar → 左侧或顶部会出现 Token 输入框（或 Auth 区域）→ 输入 Bearer eyJ… → 所有请求自动携带。
Scalar 的 Token 体验比 Swagger UI 更友好，还支持一键复制 cURL / C# 代码（已带 Token）。
额外进阶提示
- 只对需要授权的接口生效（推荐）：不要开启全局 operation.Security，而是在 Controller/Action 上正常加 [Authorize] 特性。OpenAPI 会自动识别。
- 生产环境：永远不要暴露 Swagger/Scalar（if (app.Environment.IsDevelopment()) 已保护）。
- 想让 UI 一启动就默认带某个 Token（开发测试专用，不推荐生产）：
- Swagger UI 可以注入自定义 JS（options.InjectJavascript），但较复杂。
- Scalar 支持 options.Authentication = new ScalarAuthenticationOptions { … }（详见 Scalar 官方文档）。
- 调试 Header：在浏览器 DevTools → Network 中查看请求，能确认是否真的带上了 Authorization。
这样配置后，你的接口请求就实现了“默认添加 JWT Token”的效果，一劳永逸。