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?

Analphabetic

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)SubProject\XmlDocument.xml" "$(ProjectDir)\App_Data\Subproject.xml"
   

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

3. Next open Areas\HelpPage\App_Start\HelpPageConfig 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 Areas\HelpPage\XmlDocumentationProvider 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.

Analphabetic

Excellent answer. I actually think it's a little easier for the constructor to accept an array of strings: public XmlDocumentationProvider(string appDataPath) and enumerate this list in the Documentation provider. – Repulsion

@CaptainJohn, thanks! I agree your suggestion would work well. However, I think I'll leave it as it is as it keeps most of the modifications in XmlDocumentationProvider. I was initially going to leave that line unchanged and extract the parent folder from the passed-in file, but that seemed too kludgey to me. – Analphabetic

Fantastic, this was just what I was looking for!! Suggest replacing the var files... line with var files = Directory.GetFiles(documentPath, "*.xml"); if you (like me) won't always know the names / number of xml documentation files that will be there. Could also do futher filtering as needed. – Massotherapy

Also, I only had to fix 2 references in step 4d... I'm using Web API 2.1 – Massotherapy

Any reason to not just set the XML documentation file to "App_Data\XmlDocument.xml" and skip the build step? – Contraception

@StevenBerkovitz, but then you would blow away any XML documentation for your main Web API project, right? – Analphabetic

Just because I got an error in the postbuild event, I thought it could be useful to someone who is having the same issue: copy "$(SolutionDir)SubProject\XmlDocument.xml" "$(ProjectDir)App_Data\SubProject.xml" – Sind

Simply wonderful!!! Follow the steps and works like a charm!!! Thank you @KirkWoll – Teenybopper

I would like to add my modifications on top of some of the others here. I used the ...\ notation to have the xml file created in the root project App_Data\documentation folder. I then used @sǝɯɐſ method of puling all xml files from that directory. This works beautifully and am surprised that this isn't just how it works out of the box. Many thanks. – Reliance

An excellent answer! I would suggest one small improvement. Let all your documents end with XmlDocument.xml (e.g.: Subproject.XmlDocument.xml) and replace var files = new[] { "XmlDocument.xml", "Subproject.xml" }; foreach (var file in files) with foreach (var file in Directory.EnumerateFiles(documentPath, "*XmlDocument.xml")) and remove Path.Combine call – Heliolatry

... speechless, almost crying... Friday 7pm followed this in total-dumb-mode without understanding a word. A CHARM – Seng

Maybe I'm being dense, but why not just copy all the .xml files out of the \bin directory after build? That way you get all the documentation for all the .dlls? – Maltzman

Answer 2

I ran into this too, but I didn't want to edit or duplicate any of the generated code to avoid problems later.

Building on the other answers, here's a self-contained documentation provider for multiple XML sources. Just drop this into your project:

/// <summary>A custom <see cref="IDocumentationProvider"/> that reads the API documentation from a collection of XML documentation files.</summary>
public class MultiXmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider
{
    /*********
    ** Properties
    *********/
    /// <summary>The internal documentation providers for specific files.</summary>
    private readonly XmlDocumentationProvider[] Providers;


    /*********
    ** Public methods
    *********/
    /// <summary>Construct an instance.</summary>
    /// <param name="paths">The physical paths to the XML documents.</param>
    public MultiXmlDocumentationProvider(params string[] paths)
    {
        this.Providers = paths.Select(p => new XmlDocumentationProvider(p)).ToArray();
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(MemberInfo subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(Type subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(HttpControllerDescriptor subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(HttpActionDescriptor subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(HttpParameterDescriptor subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetResponseDocumentation(HttpActionDescriptor subject)
    {
        return this.GetFirstMatch(p => p.GetResponseDocumentation(subject));
    }


    /*********
    ** Private methods
    *********/
    /// <summary>Get the first valid result from the collection of XML documentation providers.</summary>
    /// <param name="expr">The method to invoke.</param>
    private string GetFirstMatch(Func<XmlDocumentationProvider, string> expr)
    {
        return this.Providers
            .Select(expr)
            .FirstOrDefault(p => !String.IsNullOrWhiteSpace(p));
    }
}

...and enable it in your HelpPageConfig with the paths to the XML documents you want:

config.SetDocumentationProvider(new MultiXmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/Api.xml"), HttpContext.Current.Server.MapPath("~/App_Data/Api.Models.xml")));

Staysail

This is a great solution. I prefer it over solutions that require modification of the default HelpPage classes as they will be overwritten on updates. – Sager

This works brilliantly, thank you for posting. To save anyone using this a bit of time, you still need to do the first two stages of kirk's accepted answer above, i.e. 1) Enable XML documentation for your subproject and 2) Modify your Web API project's postbuild event to copy this XML file into your App_Data folder. – Jorie

and then this line becomes: config.SetDocumentationProvider(new MultiXmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/[original web api project's xml filename, defaults to XmlDocument].xml"), HttpContext.Current.Server.MapPath("~/App_Data/[Whatever you called your SubProject xml filename].xml"))); – Jorie

Followed the steps but didn't work:(. There is no error so not sure what went wrong. It still only shows the api document but not the additional project document. I also tried the steps in the accepted answer and it's the same thing. Anything in particular I should check? – Donnell

For some reason I still see the default GET api/me that comes with the getting started project template in VS. – Befall

noticed one minor thing: the GetResponseDocumentation method should return this.GetFirstMatch(p => p.GetResponseDocumentation(subject)); – Antefix

The first attempt working fine. Thanks for the solution. – Isabellaisabelle

Answer 3

One more simplified way of doing this is by merging the xml files. Example code in my below reply:

Web Api Help Page XML comments from more than 1 files

Dorene

Answer 4

Easiest way to fix this issue is creating the App_Code folder on server you deployed. Then copy the XmlDocument.xml you have in your bin folder locally into the App_Code folder

Nefarious

Thanks for suggestion!! No more -1 for such helpful answer. Yes, if you deploying it to Azure Cloud App Service, many issues occur with multiple *.xml deploying, so making them available for swagger, for example, may be really tricky. But I would rather choose another standard ASP.Net server-side folder, namely App_GlobalResources, since xmldoc files are pretty much similar to resources. It is especially true because I still did not have App_Code folder in my project and it did not matter which standard folder to create. – Junior

The following standard folder worked for me: App_Code - is not visible from client on default settings App_GlobalResources - is not visible from client on default settings App_LocalResources - is not visible from client on default settings – Junior

Let me also list out the issues with each of standard folders that did not work for me. bin - only *.xml for main assembly is deplopyed to App_Data - the most practical setting is to skip everything in this folder on deploying to cloud – Junior

Could anyone who interested edit this answer to reflect all these considerations above, probably with extended speculations? – Junior

Answer 5

I found a better solution

1. Go to properties of your solution and on Built, Out Put, Documentation XML File just fill with your folder on your app data.

2. Add a line with the file you want to insert into your documentation like this.

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

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

Louvain