.NET 7 Minimal API异步接口无法被Swagger发现生成文档问题

基于.NET 7 Minimal API搭建测试应用，将/facilities接口改为异步实现后，接口能正常响应请求，但Swagger死活生成不了该接口的文档，手动加WithOpenApi配置也完全没用，看起来Swagger根本没发现这个异步接口。

问题出在你直接操作HttpContext手动输出响应的写法上。Minimal API依赖的EndpointsApiExplorer组件（Swagger用来识别接口的核心）需要通过端点的返回类型来提取元数据，而直接操作HttpContext的方式，不管同步还是异步，都没法让它正确解析接口的请求/响应信息，自然就不会被Swagger收录。

改用Minimal API内置的返回值模式，别再手动序列化和写响应了，这样Swagger就能正常识别接口。

修改后的FacilityModule.cs代码 #

using Infrastructure.Services.Facilities;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Routing;

namespace Infrastructure.Modules
{
    public static class FacilityModule
    {
        public static void RegisterFacilityEndpoints(this IEndpointRouteBuilder endpoints, IFacilityService facilityService)
        {
            endpoints.MapGet("/facilities", async () =>
                {
                    var facilities = await facilityService.GetFacilitiesAsync();
                    return Results.Json(facilities);
                })
                .WithOpenApi(operation => new(operation)
                {
                    Summary = "获取设施列表",
                    Description = "异步获取所有设施的详细信息",
                });

            // 可添加更多端点
        }
    }
}

关键改动说明 #

• 把接收HttpContext参数的委托改成直接返回IResult的形式，这是Minimal API的标准写法。
• 用Results.Json()替代手动序列化和写入响应，它会自动设置正确的Content-Type，同时让EndpointsApiExplorer能识别响应的类型结构。
• 这样修改后，Swagger就能正常发现这个异步接口，你配置的摘要、描述也会显示在文档里。

Program.cs不需要做任何修改，保持原代码即可。

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