.NET 8 Minimal API如何自定义Swagger响应描述？

你可以通过两种无需OperationFilter的方式直接在端点代码中自定义Swagger响应描述：

方法1：使用Produces方法的重载参数 #

Produces方法提供了直接指定响应描述的重载，只需在每个Produces调用中添加description参数即可：

app.MapGet("/check/{name}", async Task<IResult> (string name, IBackupService backupService, CancellationToken cancellationToken) =>
{
    if (/*some condition*/)
    {
        return TypedResults.BadRequest();
    }

    if (/*other condition*/)
    {
        return TypedResults.Ok();
    }

    return TypedResults.Created();
    
})
    .WithName("CheckBackups")
    .WithOpenApi()
    // 为每个状态码指定自定义描述
    .Produces(StatusCodes.Status200OK, description: "Backup exists")
    .Produces(StatusCodes.Status201Created, description: "Backup created")
    .Produces(StatusCodes.Status404NotFound, description: "Backup not found")
    // 补充代码中实际返回的400状态码描述（可选）
    .Produces(StatusCodes.Status400BadRequest, description: "Invalid request parameters");

方法2：通过WithOpenApi直接修改响应配置 #

如果需要更灵活的控制，可以在WithOpenApi委托中直接修改OpenAPI操作对象的响应描述：

app.MapGet("/check/{name}", async Task<IResult> (string name, IBackupService backupService, CancellationToken cancellationToken) =>
{
    if (/*some condition*/)
    {
        return TypedResults.BadRequest();
    }

    if (/*other condition*/)
    {
        return TypedResults.Ok();
    }

    return TypedResults.Created();
    
})
    .WithName("CheckBackups")
    .WithOpenApi(op =>
    {
        // 覆盖每个响应状态码的描述
        op.Responses["200"].Description = "Backup exists";
        op.Responses["201"].Description = "Backup created";
        op.Responses["404"].Description = "Backup not found";
        // 可选：补充400状态码的描述
        if (op.Responses.TryGetValue("400", out var badReqResp))
        {
            badReqResp.Description = "Invalid request parameters";
        }
        return op;
    })
    .Produces(StatusCodes.Status200OK)
    .Produces(StatusCodes.Status201Created)
    .Produces(StatusCodes.Status404NotFound)
    .Produces(StatusCodes.Status400BadRequest);

两种方法都能生成你期望的swagger.json响应部分，无需依赖全局的OperationFilter硬编码。

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