c# - How can Xml Documentation for Web Api include documentation from beyond the main project?

Question

The documentation for enabling XmlDoc integration into your Web Api projects appears to only handle situations where all of your API types are part of your WebApi project. In particular, it discusses how to reroute the XML documentation to App_Data/XmlDocument.xml and uncommenting a line in your config that will consume that file. This implicitly only allows for one project's documentation file.

However, in my setup I have my request and response types defined in a common "Models" project. This means that if I have an endpoint defined such as:

[Route("auth/openid/login")]
public async Task<AuthenticationResponse> Login(OpenIdLoginRequest request) { ... }

Where OpenIdLoginRequest is defined in a separate C# project like so:

public class OpenIdLoginRequest
{
    /// <summary>
    /// Represents the OpenId provider that authenticated the user. (i.e. Facebook, Google, etc.)
    /// </summary>
    [Required]
    public string Provider { get; set; }

    ...
}

Despite the XML doccomments, the properties of the request parameter contain no documentation when you view the endpoint-specific help page (i.e. http://localhost/Help/Api/POST-auth-openid-login).

How can I make it so that types in subprojects with XML documentation are surfaced in the Web API XML documentation?

Answer 1

There is no built-in way to achieve this. However, it requires only a few steps:

1. Enable XML documentation for your subproject (from project properties / build) like you have for your Web API project. Except this time, route it directly to XmlDocument.xml so that it gets generated in your project's root folder.

2. Modify your Web API project's postbuild event to copy this XML file into your App_Data folder:

   copy "$(SolutionDir)SubProjectXmlDocument.xml" "$(ProjectDir)App_DataSubproject.xml"
   

   Where Subproject.xml should be renamed to whatever your project's name is plus .xml.

3. Next open AreasHelpPageApp_StartHelpPageConfig and locate the following line:

   config.SetDocumentationProvider(new XmlDocumentationProvider(
       HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));
   

   This is the line you initially uncommented in order to enable XML help documentation in the first place. Replace that line with:

   config.SetDocumentationProvider(new XmlDocumentationProvider(
       HttpContext.Current.Server.MapPath("~/App_Data")));
   

   This step ensures that XmlDocumentationProvider is passed the directory that contains your XML files, rather than the specific XML file for your project.

4. Finally, modify AreasHelpPageXmlDocumentationProvider in the following ways:

   a. Replace the _documentNavigator field with:

   private List<XPathNavigator> _documentNavigators = new List<XPathNavigator>();
   

   b. Replace the constructor with:

   public XmlDocumentationProvider(string appDataPath)
   {
       if (appDataPath == null)
       {
           throw new ArgumentNullException("appDataPath");
       }
   
       var files = new[] { "XmlDocument.xml", "Subproject.xml" };
       foreach (var file in files)
       {
           XPathDocument xpath = new XPathDocument(Path.Combine(appDataPath, file));
           _documentNavigators.Add(xpath.CreateNavigator());
       }
   }
   

   c. Add the following method below the constructor:

   private XPathNavigator SelectSingleNode(string selectExpression)
   {
       foreach (var navigator in _documentNavigators)
       {
           var propertyNode = navigator.SelectSingleNode(selectExpression);
           if (propertyNode != null)
               return propertyNode;
       }
       return null;
   }
   

   d. And last, fix all compiler errors (there should be three) resulting in references to _documentNavigator.SelectSingleNode and remove the _documentNavigator. portion so that it now calls the new SelectSingleNode method we defined above.

This Last step is what modifies the document provider to support looking within multiple XML documents for the help text rather than just the primary project's.

Now when you examine your Help documentation, it will include XML documentation from types in your related project.