Seeking guidance on correct usage of Asp.Versioning.OpenApi with full doc comment support

[KPHIBYE]

While upgrading to version 10.0.0 of this library, I tried to follow the new and revised best practices and examples from Chris Martinez and Microsoft. Everything works fine but when I checked if all my doc comments were shown in Swagger UI, I noticed that the <remarks> and <returns> sections were missing. After a bit of troubleshooting I found out that the sections in question are only correctly included in the OpenAPI document when builder.Services.AddOpenApi() is called in addition to the overload on the IApiVersioningBuilder since the Microsoft.AspNetCore.OpenApi interceptor only intercepts the libraries own methods. I also found that the handlers have to be public for this to work. Thank you for clarifying in #1200 that AOT support (enabled through #66408) is not expected until .NET 11.

My question now is, what is the "correct" way to configure both Microsoft.AspNetCore.OpenApi and Asp.Versioning such that all doc comments are supported and no redundant configuration is performed? Is an additional call to builder.Services.AddOpenApi() considered misconfiguration and is the order of the calls relevant here?

Bonus question: Why are currently all doc comments except <remarks> and <returns> correctly added to the OpenAPI document? Were they overlooked in the current implementation?

I followed these setup guides:

• https://devblogs.microsoft.com/dotnet/api-versioning-in-dotnet-10-applications/
• https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/openapi-comments

Minimal reproduction example (tested on SDK 10.0.201):

1. Please run with --no-cache
2. Uncomment builder.Services.AddOpenApi() — <remarks> and <returns> now appear in http://localhost:5000/swagger

#!/usr/bin/env dotnet
#:sdk Microsoft.NET.Sdk.Web

#:package Microsoft.OpenApi@2.11.0
#:package Microsoft.AspNetCore.OpenApi@10.0.10
#:package Asp.Versioning.OpenApi@10.0.0-rc.1
#:package Swashbuckle.AspNetCore.SwaggerUI@10.2.3

#:property PublishAot=false
#:property GenerateDocumentationFile=true
#:property InterceptorsNamespaces=$(InterceptorsNamespaces);Microsoft.AspNetCore.OpenApi.Generated
#:property Nullable=enable
#:property NoWarn=$(NoWarn);1591

using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi;

var builder = WebApplication.CreateSlimBuilder(args);

// builder.Services.AddOpenApi();

builder.Services
    .AddApiVersioning()
    .AddApiExplorer(static setup => setup.GroupNameFormat = "'v'VVV")
    .AddOpenApi(static options =>
    {
        options.Document.OpenApiVersion = OpenApiSpecVersion.OpenApi3_1;
        options.Document.AddOperationTransformer<OpenApiDeprecationTransformer>();
    });

var app = builder.Build();

app.NewVersionedApi()
   .MapGroup("api")
   .MapToDoEndpoints();

app.MapOpenApi().WithDocumentPerVersion();
app.UseSwaggerUI(options =>
{
    foreach (var description in app.DescribeApiVersions())
    {
        string name = description.GroupName;
        string url = $"/openapi/{name}.json";
        options.SwaggerEndpoint(url, name);
    }
});

app.Run();



public static class ToDoEndpoints
{
    public static IEndpointRouteBuilder MapToDoEndpoints(this IEndpointRouteBuilder endpoints)
    {
        var group = endpoints.MapGroup("ToDo").WithTags("ToDo").HasApiVersion(1);

        group.MapGet("{id}", GetToDo);
        group.MapGet("plain/{id}", GetPlainToDo);

        return endpoints;
    }

    /// <summary>Summary of the ToDo</summary>
    /// <remarks>
    /// Remark of the ToDo
    /// 
    ///     {
    ///       "title": "Cool feature"
    ///     }
    /// </remarks>
    /// <param name="id">The ID param of the ToDo</param>
    /// <returns>Returns section of the ToDo</returns>
    /// <response code="200">Response code 200 section of the ToDo</response>
    /// <response code="404">Response code 404 section of the ToDo</response>
    [Obsolete("Use the plain endpoint instead")]
    public static Results<Ok<ToDoDto>, NotFound> GetToDo(Guid id)
    {
        return TypedResults.Ok(new ToDoDto(id, "Example", "Create a minimal repro example."));
    }

    /// <summary>Summary of the plain ToDo</summary>
    /// <remarks>
    /// Remark of the plain ToDo
    /// 
    ///     {
    ///       "title": "Cool feature"
    ///     }
    /// </remarks>
    /// <param name="id">The ID param of the plain ToDo</param>
    /// <returns>Returns section of the plain ToDo</returns>
    public static ToDoDto GetPlainToDo(Guid id) => new ToDoDto(id, "Example", "Create a minimal repro example.");
}

/// <summary>A ToDo entry</summary>
/// <param name="Id">The unique ID of the ToDo</param>
/// <param name="Title">The title of the todo</param>
/// <param name="Description">The description of the ToDo</param>
/// <example>{"id":"8d186a87-97fb-457f-a07b-955ed08fc3ba","title":"Room cleaning","description":"Clean your room"}</example>
public sealed record ToDoDto(Guid Id, string Title, string Description);

public sealed class OpenApiDeprecationTransformer : IOpenApiOperationTransformer
{
    public Task TransformAsync(OpenApiOperation operation, OpenApiOperationTransformerContext context, CancellationToken cancellationToken)
    {
        var obsolete = context.Description.ActionDescriptor.EndpointMetadata.OfType<ObsoleteAttribute>().FirstOrDefault();

        if (obsolete is null)
        {
            return Task.CompletedTask;
        }

        operation.Deprecated = true;

        if (!string.IsNullOrEmpty(obsolete.Message))
        {
            string obsoleteMessage = $"This endpoint is deprecated: '{obsolete.Message}'";
            operation.Description = string.IsNullOrEmpty(operation.Description)
                ? obsoleteMessage
                : $"{obsoleteMessage}\n\n{operation.Description}";
        }

        return Task.CompletedTask;
    }
}

[commonsensesoftware]

Indeed, you are no longer meant to use builder.Services.AddOpenApi(). It is not API version-aware and, unfortunately, the design does not provide for reasonable extensibility. I've had few conversations with Microsoft and there's no simple way around it. I've had to resort to a bunch of Reflection hackery that will be addressed in .NET 11.

One of the key pain points I brought up with the ASP.NET team is the XML Comments support. It was been hacked together and is deeply coupled with Microsoft.AspNetCore.OpenApi, when it shouldn't be IMHO. In fact, there is a larger need that there should an official, general purpose XML Comment library to facilitate such things, but there isn't. The team is hesitant to create and own such a library, even though it would benefit many. Once it's out there, it's there forever (mostly*), so I get it.

The unfortunate consequence is that I've had to fork all of the XML Comment support 😞. Some of the implementation is simple and straight forward, while others are quite complex and have transformations. I tried, and thought I had, covered the core set of things people really care about. I don't have the full background history or knowledge of how or what is actually supported. Some if it didn't really make sense to me; for example, why would you have a <remarks> section with a description and example, when you already have <description> and <example>? In my effort to get something working, I have admittedly taken some shortcuts to avoid conflating things. It looks like I may be stuck with supporting the full gambit of options.

There is a work in progress that will go in the next and official release for <inheritdoc/>. As fate would have it, it is a good time to add any other gaps that people feel are important. At some future point, I may split out all of the XML Comment support into an external library, but for now it coexists in the Asp.Versioning.OpenApi because there's not another short-term option. If you want to create an issue that tracks the gaps and what needs to be addressed, I'll accept it. I at least have Microsoft's source code to go off of, but it's all wrapped up in a Source Code Generator that I can't use/re-use.

FWIW, if you're using API Versioning with OpenAPI support, you don't need a custom IOpenApiOperationTransformer to handle deprecation. That will automatically be covered when you mark an API version as deprecated. Typically, you also don't need to use ObsoleteAttribute. The one and only case I can think of where that would be used is when you version by convention (ex: version by .NET namespace). In such a scenario, discovered and collated API versions are marked as deprecated if [Obsolete] is applied, which cannot really be expressed another way. ObsoleteAttribute.Message is never used though.

The ObsoleteAttribute isn't very flexible. API authors often have to convey way more information that cannot be stuffed into a string and you don't want to be duplicating that all over the place. The deprecation and sunset policies are a much better way to advertise this information. The OpenAPI extensions will automatically render the appropriate text with applicable dates if you specified any. It also makes is possible to localize the text if that something you have support. The latest examples demonstrate how define these policies. When applicable, they will show up in the UI of your choice as well be advertised over the wire for clients to be discovered. The information is also in the OpenAPI documents as extensions if you need them for other contexts.

[KPHIBYE]

Thank you for your answer. I am glad to hear that the reflection hackery will be addressed in .NET 11.

Why would you have a <remarks> section with a description and example, when you already have <description> and <example>?

First, I did not even know that the <description> section is supported since it is not one of the recommended doc comment tags of the C# language and I was under the impression that the <remarks> section is already covering this use case. Second, I have the following use case for a <remarks> section with a description and example at my job. For historical reasons, there is mainly only one DTO per entity that is used for all modification operations on that entity, even if the actual operation ignores some of the DTO's properties. I cannot use an <example> section on the DTO since it would be shown on each endpoint, so I resorted to providing my users with minimal examples inside the <remarks> section in addition to a more thorough description.

Yes, I would like to create an issue to track the gaps. Do you want me to include any additional information in it?

Thank you for your guidance on my usage of the ObsoleteAttribute. I personally like the declarative style of controllers + attributes and was just trying to adapt it for Minimal APIs. I took a look at your examples for deprecation, version policies and version discovery and still have some gaps in my understanding, so I've opened a separate discussion (#1202) for that.

[commonsensesoftware]

You are correct. <description> and <response> are not standard XML Comment tags. There are some built-in tags that are well-konwn or even have meaning to the compiler, but much of it is free-form. Even the documentation calls it Recommended XML Documentation Tags. There have long been custom tags since the days of Sandcastle (dating myself). IIRC, <inheritdoc /> originally was not a recommended tag, but now it is. <description> and <response code="###"> were popularized by Swashbuckle. Even though they aren't standard, pretty much everyone supports them now.

I've create issue #1205 to track the tags that don't have parity with Microsoft.AspNetCore.OpenApi. If you can think of more or find something I missed, feel free to comment or add your thoughts to the issue.