Improve OpenAPI/Swagger response metadata for returned IResults

[halter73]

Today, when you return an IResult from a minimal action, you lose all metadata about the type of the response (see #33433). You can add the metadata back with something like [ProducesResponseType(typeof(Person), 201], but in many cases the response type could be inferred from the IResult implementation if we designed a way for this to work.

The most obvious idea is to do like ActionResult<TValue> though implicit conversions with interfaces might make this tricky.

We've moved this issue to the Backlog milestone. This means that it is not going to be worked on for the coming release. We will reassess the backlog following the current release and consider this item at that time. To learn more about our issue management process and to have better expectation regarding different types of issues you can read our Triage Process.

[halter73]

Another option is adding extension methods on MinimalActionEndpointConventionBuilder that adds the Produces*Attributes as endpoint metadata.

Here's an example from @DamianEdwards showing how this could look.

app.MapPost("/todos", async (Todo todo, TodoDb db) =>
{
    if (!MinimalValidation.TryValidate(todo, out var errors))
        return Results.ValidationProblem(errors);

    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todos/{todo.Id}", todo);
})
.ProducesValidationProblem()
.Produces<Todo>();

[DamianEdwards]

That example (and a few more) are from a functional prototype/example at https://github.com/DamianEdwards/MinimalApiPlayground/blob/main/src/MinimalApiPlayground/Program.cs

[martincostello]

Something like that would be good.

I've done a similar thing with the project I've been trying minimal actions out with: https://github.com/martincostello/dotnet-minimal-api-integration-testing/blob/2c9bf003d8213e73d06729d0001d48952f6fa741/src/TodoApp/ApiModule.cs#L31-L32

I've suggested a similar thing for ignoring the endpoints too in #34068.

Though at the same time it's made me wonder at what point the dividing line between minimal actions and "growing up" to moving "back" to a controller is?

Not a criticism as it's a new different style of implementing APIs, it's just that with a bunch of annotations on an action that's only a few lines of code it's suddenly a lot less...minimal 🙂

[DamianEdwards]

@martincostello I actually think one of the benefits of the minimal API style is that the extension methods are (admittedly subjectively) less ceremony and far easier to discover than the attributes. The attribute names are somewhat fixed now but it's easy for us to add method overloads that do more/less/allow differing expression.

[DamianEdwards]

Also I do think at some point we'll enable hopefully much of this as a convention/automatically so that one doesn't need to describe the response shape manually at all, e.g. via a source generator.