FastEndpoints集成Swagger后不显示摘要信息问题排查

问题描述 #

使用FastEndpoints搭配Swagger时，端点可被Swagger识别并展示，但配置的摘要信息无法显示。相关代码如下：

端点Configure方法代码 #

public override void Configure()
{
    this.Get("/devicelogs/{DeviceId}/");
    this.AllowAnonymous();

    Summary(s => {
        s.Summary = "short summary goes here";
        s.Description = "long description goes here";
        s.Responses[200] = "ok response description goes here";
        s.Responses[403] = "forbidden response description goes here";
    });
    this.Description(
        b => b
            .WithName("GetDeviceLog")
            .Accepts<GetDeviceLogRequest>("application/json")
            .Produces<GetDeviceLogResponse>(200, "application/json")
    );
}

Startup相关配置代码 #

services
    .AddFastEndpoints()
    .AddSwaggerDocument(
        x =>
        {
            x.Description = "Proxy Http Endpoints";
            x.Title = "Proxy Http Endpoints";
        });

app.UseSwaggerGen(x =>
{
    x.DocumentName = "Proxy Http Endpoints";
});
app.UseEndpoints(endpoints =>
{
    endpoints.MapFastEndpoints();
 });

解决方法 #

1. 删除冲突的Description()配置 #

FastEndpoints的Summary()方法已经专门负责Swagger的摘要、描述和响应信息配置，额外添加的Description()方法会覆盖Summary()里的设置，导致摘要无法显示。直接移除this.Description(...)这段代码即可。

2. 修正Swagger中间件配置 #

当前混用了NSwag的AddSwaggerDocument()和Swashbuckle的UseSwaggerGen()，这是错误的。FastEndpoints默认集成NSwag，正确的中间件配置应替换为：

// 替换原来的UseSwaggerGen部分
app.UseOpenApi();
app.UseSwaggerUi3(x =>
{
    x.DocumentName = "Proxy Http Endpoints";
    x.Path = "/swagger"; // Swagger UI的访问路径
});

3. 确认端点类继承关系 #

确保你的端点类正确继承自Endpoint<GetDeviceLogRequest, GetDeviceLogResponse>，这样Summary()中的配置才能正确绑定到对应的请求和响应模型，Swagger才能正确读取这些信息。

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