.NET Core 7中gRPC集成Swagger失败，报HTTP版本不兼容错误

原因分析 #

gRPC服务默认依赖HTTP/2协议，但Swagger UI及gRPC JSON转码接口使用HTTP/1.1协议请求。若项目的Kestrel服务器仅配置为支持HTTP/2，就会触发协议冲突错误。

解决方案 #

1. 配置Kestrel同时支持HTTP/1.1和HTTP/2 #

在Program.cs的WebApplication.CreateBuilder阶段，添加Kestrel双协议支持配置：

builder.WebHost.ConfigureKestrel(options =>
{
    // 配置HTTP端口支持双协议
    options.ListenAnyIP(5000, o => o.Protocols = HttpProtocols.Http1AndHttp2);
    // 若使用HTTPS，同步配置双协议
    options.ListenAnyIP(5001, o =>
    {
        o.Protocols = HttpProtocols.Http1AndHttp2;
        o.UseHttps();
    });
});

2. 调整中间件顺序 #

确保Swagger相关中间件在路由配置前启用，认证授权中间件按需添加：

var app = builder.Build();

// 启用Swagger
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

// 启用路由
app.UseRouting();

// 启用认证与授权（项目有相关逻辑时添加）
app.UseAuthentication();
app.UseAuthorization();

// 映射gRPC服务，同时支持gRPC原生请求与HTTP转码请求
app.UseEndpoints(endpoints =>
{
    endpoints.MapGrpcService<GreeterService>();
});

app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");

app.Run();

3. 确认gRPC与Swagger集成服务注册 #

检查项目中已正确添加以下服务注册（你的代码已包含，可验证版本兼容性）：

builder.Services.AddGrpcHttpApi();
builder.Services.AddGrpcSwagger();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "gRPC Server", Version = "v1" });
    var filePath = Path.Combine(System.AppContext.BaseDirectory, "gRPCserver.xml");
    c.IncludeXmlComments(filePath);
    c.IncludeGrpcXmlComments(filePath, includeControllerXmlComments: true);
});

4. 检查启动配置 #

在launchSettings.json中，确保应用启动URL使用兼容HTTP/1.1的端口，未强制指定仅使用HTTP/2。

验证 #

重启项目后，访问/swagger/index.html即可正常加载Swagger文档，同时gRPC服务仍可通过HTTP/2正常运行。

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