XML Comments Do Not Have Parity with Microsoft.AspNetCore.OpenApi

[commonsensesoftware]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

The XML Comment support provided in Asp.Versioning.OpenApi does not have the same parity and fidelity of the support provided by Microsoft.AspNetCore.OpenApi. The features and support should be equivalent.

The following tags and features are currently unsupported:

• <c>
• <code>
• <returns>
• <paramref>
• <list>
• <value>
• <para>

Expected Behavior

No response

Steps To Reproduce

No response

Exceptions (if any)

No response

.NET Version

No response

Anything else?

No response

[KPHIBYE]

I have tested your latest commit (4af87fc) that includes the fix for this issue, but I found two problems:

1. The <remarks> tag is still unsupported (it should have priority over <description> as can be seen in XmlCommentGenerator.Emitter.cs)
2. The <code> tag doesn't seem to work correctly

Example I used for testing

/// <summary>Summary of GetToDo</summary>
/// <description>
/// Remark of GetToDo
/// 
/// <code>
///     var index = 5;
///     index++;
/// </code>
/// 
/// <list type="bullet">
///     <listheader>
///         <term>term</term>
///         <description>description</description>
///     </listheader>
///     <item>
///         <term>Assembly</term>
///         <description>The library or executable built from a compilation.</description>
///     </item>
///     <item>
///         <term>Namespace</term>
///         <description>A logical grouping of related types such as classes and interfaces.</description>
///     </item>
///     <item>
///         <term>Class</term>
///         <description>A blueprint used to create objects, containing properties and methods.</description>
///     </item>
/// </list>
/// 
/// <para>
///     This is an introductory paragraph of the <c>GetToDo()</c> method.
/// </para>
/// <para>
///     This paragraph contains more details about <paramref name="id"/>.
/// </para>
/// </description>
/// <param name="id">The ID param of the ToDo</param>
/// <returns>Returns section of the ToDo</returns>
private static ToDoDto GetToDo(Guid id)
{
    return new ToDoDto(id, "Example", "Create a minimal repro example.");
}

Expected (produced via AI generated patch)	Actual

[commonsensesoftware]

Re-opened

Interesting. I don't understand why the implementation would read <description> and write to Description just to immediately overwrite it with <remarks>. I have no problem making the parity consistent, but I feels <remarks> should be set first and then <description> if it's still empty. I'm not sure why anyone would do both. 🤷🏽 I have the support to read <remarks>, but I guess I goofed on actually using it. 🤦🏽

The <code> handling is clearly wrong. Thanks for the patch. I'll get this incorporated. Both of these fixes will go out in the next patch. I'm actively working on some changes. It should go out in a few days.

Thanks for reporting the issue(s) and continuing to provide feedback. Since you've engaged, there's a few other things I would value your opinion on.

The Microsoft implementation had at 3 bugs in handling <list>:

1. Numbered lists did not work. The number was hardcoded with a "1. " prefix. No idea why, but I fixed that. It should work correctly.
2. Bulleted lists with <term> and <description> were just mashed together; now, it has the form of * **<term>**: <description>
   • Your example highlights this difference without complaint, so I presume this is the preferred behavior
3. Tables were mashed together as a bulleted list; now, they are markdown tables, even if there are no headers
   • I can't think of a reason anyone would not want this behavior, but if you can think of one, it might be worth a configuration setting
   • Not all Swagger UIs like Scalar or Swashbuckle handle Markdown in all areas the same way
     • I leave it to developers to know and decide where they can or can't use a table

Any preference on whether * or - is used for bullets? Personally, I normally use -, but I kept it as * for this specific case. In makes zero difference for rendering, but there is a slight difference for reading the raw Markdown.

Please report any other differences if you notice them. Some things I purposely left out include:

• <typeparam>
• <typeparamref>
• <cref>
• <see>
• <seealso>

These are all C#/.NET specific which don't have any meaning in OpenAPI. I also noticed that there are some recommend tags that still aren't supported, but could be:

• <b>
• <i>
• <u> (no Markdown equivalent though)
• <a>

These could be supported now or easily added later. It wasn't supported before so it would be an enhancement over a deviation.

[KPHIBYE]

I want to clarify something regarding the patch. It is purely AI generated and was not reviewed by me. I included it to be fully transparent on how I achieved the "Expected" screenshot. It may contain unnecessary code and might not adhere to your design guidelines or best practices, so please check the code before incorporating it.

Regarding <list>:

1. I can confirm that the hardcoded "1. " is fixed. The reason for the hardcoding could be that Markdown does not care about numbering except for the first element.
2. I can also confirm that the boldness of <term> and the ": " separator look very nice. Furthermore, I noticed that numbered lists also benefit from this change.
3. I also can't think of a reason anyone would not want this behavior since they could simply switch to <list type="bullet"> to get the old behavior back.

I would stick with * since the Microsoft implementation also uses it.

I also don't see an immediate use case for the tags you left out.

While I highly appreciate new features, especially when they can be implemented without much effort (assuming this is the case here), I am of the opinion that a stable and bug-free .NET 10 release should have priority. Also, note that when supporting <b> and <i>, combining them has to be handled correctly.

I hope this input helps :)