[OpenApi] xml doc not used when endpoint delegate is async

[jasonswearingen]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

endpoints with async handlers do not have the xml doc properly applied to the openapi .json output.

I define endpoints like this:

RouteGroupBuilder dashboardEndpoints = app.MapGroup("/dashboard/v1");
dashboardEndpoints.MapGet("Test", Test);
dashboardEndpoints.MapGet("TestAsync", TestAsync);

with handlers defined as:

/// <summary>
/// Test summary
/// </summary>
/// <returns>Test return</returns>
public static IResult Test()
{
    return TypedResults.Conflict();
}
/// <summary>
/// TestAsync summary
/// </summary>
/// <returns>TestAsync return</returns>
public static async Task<IResult> TestAsync()
{
    return TypedResults.Conflict();
}

This results in the following openapi .json contents. as you can see, the "TestAsync summary" message is not output

"/dashboard/v1/Test": {
    "get": {
    "tags": [
        "DashboardApiInit"
    ],
    "summary": "Test summary",
    "responses": {
        "200": {
        "description": "OK"
        }
    }
    }
},
"/dashboard/v1/TestAsync": {
    "get": {
    "tags": [
        "DashboardApiInit"
    ],
    "responses": {
        "200": {
        "description": "OK"
        }
    }
    }
},

Expected Behavior

async methods should have xml docs utilized properly

Steps To Reproduce

see above

Exceptions (if any)

none

.NET Version

10.0.100-preview.3.25201.16

Anything else?

Microsoft.AspNetCore.OpenApi v10.0.0-preview.3.25172.1

[captainsafia]

@jasonswearingen I believe the issue here is the use of the <returns> comment. The XML comment implementation currently only supports the <response> annotation for responses. See the example below.

/// <summary>
/// A summary of Get15.
/// </summary>
/// <response code="200">Returns the greeting.</response>
public static Task<Holder<string>> Get15()
{
    return Task.FromResult(new Holder<string> { Value = "Hello, World!" });
}

We can consider adding support for returns as well, although we'd have to consider what the default behavior would be:

• Should it be the description for all the responses that are generated from an endpoint?
• Should it only kick in if a method exposes a single response?
• Should it be set as the description for the default response.

I lean towards 2 in the above list.

[jasonswearingen]

@captainsafia I do not think <returns> is related. This is specific about <summary> xml docs not being used when a method is marked async.

However as per your request to retry, I have not yet been able to repro this, as I needed to move to .Net 9 due to infrastructure limitations. But your described solution does not seem related at all.