Repository navigation
XML Comments Do Not Have Parity with Microsoft.AspNetCore.OpenApi #1205
Description
Activity
- added a commit that references this issue
on Jul 29, 2026 I have tested your latest commit (4af87fc) that includes the fix for this issue, but I found two problems:
- The
<remarks>tag is still unsupported (it should have priority over<description>as can be seen in XmlCommentGenerator.Emitter.cs) - 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 
- The
Re-opened
Interesting. I don't understand why the implementation would read
<description>and write toDescriptionjust 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>:- Numbered lists did not work. The number was hardcoded with a
"1. "prefix. No idea why, but I fixed that. It should work correctly. - 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
- 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.
- Numbered lists did not work. The number was hardcoded with a
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>:- 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. - 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. - 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 :)
- I can confirm that the hardcoded
- added a commit that references this issue
on Aug 6, 2026 10.2.0has dropped with all of these fixes and enhancements in. I tried the exact content provided and it rendered exactly as expected. Since I hastily closed the issue too early last time, @KPHIBYE have a look-see and make sure I didn't miss anything. We can close it once you have verified the behavior on your side.Thank you for this big update and for asking for my feedback. While I can confirm that my provided example renders correctly and the
<b>,<i>,<u>and<a>tags behave mostly as expected, I have to inform you that/// <summary>This is a summary</summary> /// <remarks> /// Text before code /// /// <code> /// var index = 5; /// index++; /// </code> /// /// Text after code /// </remarks>
produces an incorrect description in the generated OpenAPI document:
"description": " Text before code\n\n\n```\nvar index = 5;\nindex++;\n```\n\n\n Text after code".Since four or more leading spaces mark an indented code block in Markdown, both text lines are rendered as code.
If the summary section is removed, empty, or if its opening and closing tags are on their own lines,
"description": "Text before code\n\n\n```\nvar index = 5;\nindex++;\n```\n\n\nText after code"is produced which looks as expected.A
<list>in place of the<code>block shows the same symptom.Another wrong behavior is that whitespaces between two adjacent inline tags are removed and that switching the order of immediately nested
<b>and<i>tags produces different output:/// <para> /// <b>Remark <i>of</i></b> <u>GetToDo</u> /// </para> /// <para> /// <b>Remark</b> <i>of</i> <u>GetToDo</u> /// </para> /// <para> /// Very<b><i>long</i></b>word /// </para> /// <para> /// Very<i><b>long</b></i>word /// </para>
As mentioned before, translating
<i>to*could potentially fix the ordering problem of<b>and<i>.Real world examples of what someone does or might do is extremely valuable. Thanks for engaging. I don't really have a sample population to take examples from. Whitespace preservation is always tricky. It seems the desired behavior is to trim the leading and trailing whitespace, but preserve everything else. This might be better defined by explicitly requiring
xml:space="preserve", which is the idiomatic way retain it in XML.This is very much turning to a XML to Markdown Converter. I can see that extracted (eventually) to a library of its own with specific conversion options. At some point, it might be worth spinning up an issue or discussion to track such requirements.
I'll take a crack at addressing these. I'll circle back around for review before the next patch.
- added a commit that references this issue
on Aug 11, 2026 10.2.2 with the latest changes and fixes. Let me know if any other edge cases come up.
I have run some tests and besides some behavior that is not a problem such as
<para>,<code>and<list>inside lists or backticks inside<c>(in my opinion support for these things is unreasonable), that is easily avoided such as missing whitespaces because of writing<b>bold </b>tailinstead of<b>bold</b> tailand some things that I am not sure of if they should be supported such as<see href="url"></see>as alternative to<a href="url"></a>, I have found two behaviors that are in my opinion still wrong.- Text immediately following a list is included in the list
- Links without anchor text are not clickable in Swagger UI while being clickable in Scalar
- Do you think it would be feasible to use the URL as anchor text if none or only whitespaces are given as anchor so that
[]()can be generated?
- Do you think it would be feasible to use the URL as anchor text if none or only whitespaces are given as anchor so that
Example:
/// Text before list /// <list type="number"> /// <item><description>First step</description></item> /// <item><description>Second step</description></item> /// </list> /// Text after list /// /// <a href="https://example.org/spec"></a> /// /// <a href="https://example.org/spec" />
Other than that, the update seems to be very polished. Thank you for your hard work and incorporation of my feedback.
Reacted by Chris MartinezThanks for taking the time to test things out and provide additional feedback.
- This is definitely an issue.
<list>should be processed as a block just like a table - This is just an omission; yes, if there's no explicit link text, then it should fall back to the link itself
<see href="...">and<seealso href="...">are the old DocFX and Sandcastle conventions, but I don't see a reason to not support them; adding- Nesting can be nuanced; especially inside
<code>. This can be considered in the future, but this should be sufficient for now
I'm working on another round of changes and I'll get it out ASAP.
- This is definitely an issue.
- added a commit that references this issue
on Aug 22, 2026 - added a commit that references this issue
on Aug 22, 2026 10.2.3 has been published. Hopefully, that will close the last of the gaps. Thanks for continuing to provide feedback. I'm sure it will save the community from previously missed edge cases.
I believe this issue has finally stabilized and addressed all (or most) of the edge cases. Thanks for the participation and feedback. It got things to a better place. At some future state, I'll like to rip all of the XML Comment support out into a separate library, but that is a problem for another day.
Is there an existing issue for this?
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