在ASP.NET Core 6中使用FastEndpoints为Swagger请求添加自定义Header

1. 全局配置两个Header（适用于所有接口） #

在AddSwaggerDoc的配置逻辑中，补充全局参数定义和安全要求配置，让Swagger UI自动生成对应的输入项：

builder.Services.AddSwaggerDoc(settings =>
{
    settings.Title = "IPR Backend API";
    settings.Version = "v1";
    
    // 保留原有ApiKey认证配置
    settings.AddAuth("ApiKeyAuth", new()
    {
        Name = "ApiKey",
        In = NSwag.OpenApiSecurityApiKeyLocation.Header,
        Type = NSwag.OpenApiSecuritySchemeType.ApiKey,
    });

    // 添加全局CorrelationId Header参数
    settings.AddParameter(new NSwag.OpenApiParameter
    {
        Name = "CorrelationId",
        In = NSwag.OpenApiParameterLocation.Header,
        Required = true, // 根据实际业务需求设置是否必填
        Description = "请求关联ID，用于链路追踪"
    });

    // 启用全局ApiKey安全要求，让所有接口默认携带ApiKey
    settings.AddSecurityRequirement(new NSwag.OpenApiSecurityRequirement
    {
        {
            new NSwag.OpenApiSecuritySchemeReference { Id = "ApiKeyAuth" },
            Array.Empty<string>()
        }
    });
}, addJWTBearerAuth: false);

app.UseOpenApi();
app.UseSwaggerUi3(s => s.ConfigureDefaults());

2. 验证配置效果 #

启动项目打开Swagger UI后：

• 点击右上角Authorize按钮，输入ApiKey的值提交，后续所有请求都会自动携带该Header。
• 每个接口的请求参数区域会出现CorrelationId输入框，填入对应值即可发起测试请求。

3. 局部配置（仅部分接口需要CorrelationId） #

如果CorrelationId不是所有接口都需要，可在对应FastEndpoints的请求模型中用[Header]标记参数，Swagger会自动识别生成输入项：

public class SampleEndpoint : Endpoint<SampleRequest>
{
    public override void Configure()
    {
        Post("/api/sample");
        AllowAnonymous();
    }

    public override async Task HandleAsync(SampleRequest req, CancellationToken ct)
    {
        // 业务逻辑处理
    }
}

public class SampleRequest
{
    [Header("CorrelationId")]
    public string CorrelationId { get; set; } = string.Empty;
}

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