ASP.NET XML Docs with implied 'summary' tag

Question

I want my ASP.NET (C#) project to show the XML docs comments in Swagger UI. This is working but I also want there to be an implicit <summary> tag on my comments.

E.g. I want this to work

/// List orgs 1 page at a time

instead of having to do this

/// <summary>List orgs 1 page at a time</summary>

Is there a way achieve this?

My learn-asp8 project illustrates the issue in Controller1.cs

Ideas:

Customize how the XML docs file is generated
Massage the XML docs file before it is used
Customize Swagger / OpenAPI spec generator to wrap in <summary> tag if necessary

I don't think that this is possible natively. The C# compiler requires properly formatted XML documentation comments. So you must explicitly use <summary>, <param>, <returns>, etc. What you could do is to preprocess the XML doc file before Swagger uses it. — AztecCodes
– AztecCodes, Commented Apr 25 at 23:46
Thanks @AztecCodes. My IDE seems happy without the tags. F# seems to have implied <summary> documented but yes, C# technically must have explicit. I was hoping someone could tell me what mechanism to use for preprocessing. — Peter L
– Peter L, Commented Apr 28 at 19:52

Peter L · Accepted Answer · 2025-04-29 00:48:20Z

It was a bit fiddly but here is my answer....

SwaggerGenOptionsExtensions has a mechanism to customize the XML Docs file. This code wraps the contents of <member> tags in <summary> if none are present.

From Program.cs:

builder.Services.AddSwaggerGen(options =>
{
   // ...

   // Include XML Docs in Swagger UI
   var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
   var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
   XPathDocument CustomizeDocs() => ProgramHelper.InsertSummaryTags(xmlPath);
   options.IncludeXmlComments(CustomizeDocs, includeControllerXmlComments: true);
});

And the code to massage XML:

/// Ensures all '/doc/members/member' tags contain a 'summary' tag by wrapping contents when no 'summary' tag is found
public static XPathDocument InsertSummaryTags(string inputFile)
{
   if (!File.Exists(inputFile))
   {
       throw new FileNotFoundException($"The input file '{inputFile}' does not exist.");
   }


   // Load the XML using XPathDocument
   var doc = new XPathDocument(inputFile);
   var navigator = doc!.CreateNavigator();


   // Create output document
   var workingDoc = new XmlDocument();
   workingDoc.LoadXml(navigator.OuterXml);


   // Select all member nodes
   XmlNodeList? memberNodes = workingDoc.SelectNodes("//doc/members/member");


   if (memberNodes != null)
   {
       foreach (XmlNode memberNode in memberNodes)
       {
           // Check if summary element already exists
           XmlNode? existingSummary = memberNode.SelectSingleNode("summary");


           if (existingSummary == null && memberNode.HasChildNodes)
           {
               // Create a new summary element
               XmlElement summaryElement = workingDoc.CreateElement("summary");


               // Create a list to store all child nodes
               List<XmlNode> childNodes = new List<XmlNode>();
               foreach (XmlNode child in memberNode.ChildNodes)
               {
                   childNodes.Add(child);
               }


               // Move all child nodes to the summary element
               foreach (XmlNode child in childNodes)
               {
                   memberNode.RemoveChild(child);
                   summaryElement.AppendChild(child);
               }


               // Add the summary element to the member
               memberNode.AppendChild(summaryElement);
           }
       }
   }


   // Convert modified XmlDocument back to XPathDocument
   using MemoryStream ms = new MemoryStream();
   workingDoc.Save(ms);
   ms.Position = 0;
  
   return new XPathDocument(ms);
}

My learn-asp8 project now has the fix.

Collectives™ on Stack Overflow

ASP.NET XML Docs with implied 'summary' tag

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related