如何配置ASP.NET Core 9 Web API使Swagger测试时发送客户端密钥请求头

1. 请求未携带客户端密钥的原因 #

你仅在OpenAPI文档中定义了安全方案（SecurityScheme），但未添加安全要求（Security Requirement），Swagger UI无法得知需要将该密钥附加到接口请求中。只有当接口被标记需要安全验证时，Swagger UI才会自动把用户输入的密钥带入请求头。

2. Scheme设置错误的问题 #

你的客户端密钥是纯字符串，不需要bearer前缀，因此SecuritySchemeType.Http+Scheme = "bearer"的配置完全错误。正确的类型应该是SecuritySchemeType.ApiKey，该类型专门用于自定义API密钥头，不会为密钥添加任何额外前缀。

修正后的完整代码 #

var builder = WebApplication.CreateBuilder(args);

// ... 其他服务配置

builder.Services.AddOpenApi(o =>
{
    o.AddDocumentTransformer((document, context, cancellationToken) =>
    {
        document.Components ??= new OpenApiComponents();
        // 定义ApiKey类型的安全方案
        document.Components.SecuritySchemes["Client-Secret-1"] = new OpenApiSecurityScheme
        {
            Type = SecuritySchemeType.ApiKey,
            Name = "Client-Secret-1", // 请求头的名称
            In = ParameterLocation.Header,
            Description = "请输入客户端密钥"
        };

        // 添加全局安全要求：所有接口都需要携带该密钥
        document.Security ??= new List<OpenApiSecurityRequirement>();
        document.Security.Add(new OpenApiSecurityRequirement
        {
            {
                new OpenApiSecurityScheme
                {
                    Reference = new OpenApiReference
                    {
                        Type = ReferenceType.SecurityScheme,
                        Id = "Client-Secret-1"
                    }
                },
                new string[] {}
            }
        });

        return Task.CompletedTask;
    });
});

var app = builder.Build();

// ... 中间件配置

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/openapi/v1.json", "MyProjectName");
    });
}

// ... 路由配置

app.Run();

额外说明 #

• 若不需要全局应用密钥验证，仅针对特定接口生效，可以在控制器或Action上添加[Authorize]属性，或者手动为目标接口的OpenAPI元数据单独添加安全要求。
• 修正后，Swagger UI顶部会出现「Authorize」按钮，用户输入密钥后，所有请求都会自动带上Client-Secret-1请求头，且值为用户输入的纯字符串，不会附加任何前缀。

内容的提问来源于stack exchange，提问作者ConfuedProblemSolver