ASP.NET Core OpenAPI 如何配置自定义 Authorization 请求头？

2026-11-04数据小许

结论

若要让 Swagger UI 原样发送 Authorization: CUSTOMSCHEME key="13431"，请将 API key 方案的请求头名称设为 Authorization，并在 Swagger UI 的授权输入框中填写完整值 CUSTOMSCHEME key="13431"。BearerFormat 不会为 apiKey 方案拼接这段内容，Scheme 也不能用来指定 API key 方案的请求头名称。

var securitySchemes = new Dictionary<string, IOpenApiSecurityScheme>
{
    ["CustomScheme"] = new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.ApiKey,
        Name = "Authorization",
        In = ParameterLocation.Header
    }
};

document.Components ??= new OpenApiComponents();
document.Components.SecuritySchemes = securitySchemes;

在 Swagger UI 的授权输入框中输入：

CUSTOMSCHEME key="13431"

这样配置后，Swagger UI 会将输入内容作为 Authorization 请求头的值发送，不会根据 Scheme 或 BearerFormat 自动添加前缀。

为什么现有配置不符合预期

原代码设置了 In = ParameterLocation.Header，但没有设置 Name。对于 SecuritySchemeType.ApiKey，Name 用于指定请求头名称，因此应设为 Authorization。BearerFormat 只是描述令牌格式的提示信息，不会把输入值转换成 key="..."；Scheme 也不能代替 Name 指定 API key 请求头。

如果希望 Swagger UI 自动添加 scheme 前缀

如果希望授权输入框只接收 key="13431"，并由 Swagger UI 自动添加 CUSTOMSCHEME，可以考虑使用 HTTP 安全方案：

new OpenApiSecurityScheme
{
    Type = SecuritySchemeType.Http,
    Scheme = "CUSTOMSCHEME"
}

这种方式取决于 Swagger UI 对自定义 HTTP scheme 的处理行为，以及当前 OpenAPI 与 Swashbuckle 版本的兼容情况。若要确保 Authorization 值按指定文本原样发送，使用 apiKey 方案并在输入框中填写完整值更直接。

还要让方案应用到接口

将安全方案加入 document.Components.SecuritySchemes 只是完成定义，不一定会让 Swagger UI 将其应用到某个接口。还需要根据当前使用的 OpenAPI 模型，为需要保护的文档或操作添加对应的 security requirement。具体写法取决于所用的 Microsoft.OpenApi 版本和 API。若未添加 requirement，授权方案可能不会影响接口请求。