.NET 8中使用Results.Ok时如何让Swagger显示输出类型？

当使用Results.Ok包裹返回值时，Swagger无法自动推断输出类型，需要通过以下方式显式指定：

方法一：显式指定端点返回类型 #

在MapGet后通过泛型参数声明返回的类型，框架会自动关联到Swagger文档：

IEndpointRouteBuilder app = //...
app.MapGet<UserBalance>("users/foo", () =>
{
    return Results.Ok(new UserBalance() { /* ... */ });
})
.WithName("GetFoo").WithOpenApi();

方法二：使用WithProducesResponseType扩展方法 #

通过该方法直接指定200状态码对应的输出类型：

IEndpointRouteBuilder app = //...
app.MapGet("users/foo", () =>
{
    return Results.Ok(new UserBalance() { /* ... */ });
})
.WithProducesResponseType<UserBalance>(StatusCodes.Status200OK)
.WithName("GetFoo").WithOpenApi();

方法三：使用ProducesResponseType特性 #

在端点委托上添加特性，声明响应类型和状态码：

IEndpointRouteBuilder app = //...
app.MapGet("users/foo", [ProducesResponseType(typeof(UserBalance), StatusCodes.Status200OK)] () =>
{
    return Results.Ok(new UserBalance() { /* ... */ });
})
.WithName("GetFoo").WithOpenApi();

原因说明 #

直接返回UserBalance时，ASP.NET Core框架能自动推断端点的返回类型并同步给Swagger；但返回IResult（Results.Ok的返回类型）时，框架无法解析内部封装的具体类型，因此必须显式声明才能让Swagger正确展示输出内容。

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