Controller method in referenced project not mapped

[rkreis-v]

When controller functions are defined in a project reference rather than the target assembly (so they go through ParseXmlFile), doc strings are not added to the OpenApi output. Added this to models project:

public static class ExtraApis
{
    /// <summary>
    /// No doc
    /// </summary>
    /// <param name="app"></param>
    public static void MapExtraApis(this IEndpointRouteBuilder app)
    {
        var extraGroup = app.MapGroup("/api/extra");

        extraGroup.MapGet("/test-xml-doc-comment", TextXmlDocComment);
    }

    /// <summary>
    /// Test endpoint for xml doc comment
    /// </summary>
    /// <returns>A collection of todos for the specified project board.</returns>
    /// <response code="200">Returns the list of todos.</response>
    /// <response code="404">If the project board is not found.</response>
    public static IResult TestXmlDocComment()
    {
        return Results.Ok();
    }
}

It's exported to Models.xml:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Models</name>
    </assembly>
    <members>
[...]
        <member name="M:ExtraApis.TestXmlDocComment">
            <summary>
            Test endpoint for xml doc comment
            </summary>
            <returns>A collection of todos for the specified project board.</returns>
            <response code="200">Returns the list of todos.</response>
            <response code="404">If the project board is not found.</response>
        </member>
[...]

OpenApiXmlCommentSupport.generated.cs has this XmlComment entry:

            cache.Add(@"M:ExtraApis.TestXmlDocComment", new XmlComment(@"Test endpoint for xml doc comment", null, null, @"A collection of todos for the specified project board.", null, false, null, null, [new XmlResponseComment(@"200", @"Returns the list of todos.", @""), new XmlResponseComment(@"404", @"If the project board is not found.", @"")]));

But CreateDocumentationId(MethodInfo) returns:

methodInfo.CreateDocumentationId()
"M:ExtraApis.TestXmlDocComment~Microsoft.AspNetCore.Http.IResult"

Including the return type, which doesn't match Models.xml.

[captainsafia]

@rkreis-v Thanks for filing this issue! I was able to successfully reproduce it.

So, return types are not included in the documentation IDs that are emitted to disk since return types do not play a role in disambiguation like parameters do.

For generating documentation IDs from types that are in the current assembly, we use the Roslyn DocumentationCommentId.CreateDeclarationId method which retains the return type in the documentation ID for internal bookkeeping.

We can likely solve this by updating our documentation ID generator to stop emitting the return types and pruning the return types from the ID produced by the Roslyn API above.

[Trivivium]

Related issue, but focused on Minimal APIs: dotnet/aspnetcore#62216

[captainsafia]

@Trivivium Thanks for filing that issue! Apologies for the delay in processing it. I think the plan outlined in dotnet/aspnetcore#62691 will solve the problem for both minimal and controller-based APIs.

[captainsafia]

Fixed via 1f43a62.