Web Api: enable XML documentation for your subproject (external assembly)

I would admit that this post it’s simply a copy/paste of a stackoverflow response, that was really well done and IMHO should also be in the documentation! of course I up-voted that post 🙂

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.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:
    1. Replace the _documentNavigator field with:
      private List<XPathNavigator> _documentNavigators = new List<XPathNavigator>();
    2. 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());
          }
      }
    3. 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;
      }
    4. 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.

Advertisements

2 thoughts on “Web Api: enable XML documentation for your subproject (external assembly)”

  1. Hey thanks very much man for your post, only if you can explain more on this line “copy $(SolutionDir)SubProject\XmlDocument.xml $(ProjectDir)\App_Data\Subproject.xml” its kind of unclear, especial in inside those brackets eg (SolutionDir) not sure what to writte there, (SubProject\XmlDocument.xml) , not sure what “SubProject is”, otherwise other stuff is clear and understandable.

  2. Sorry to reply you so late.

    For subproject I mean the project (class library) that you reference from the main asp.net web api project, the project that probably contains all the models exposed by the web api and that has comments on it and that can be documented in the help page by changing the code and copying the generated xml file into app_data folder of the web api project.

    The “copy $(SolutionDir)SubProject\XmlDocument.xml $(ProjectDir)\App_Data\Subproject.xml” should be set on the “Post-Build event command line” field of your web api project settings, you can find by right clicking on the project then select properties and finally the “Build Events” tab, there you find the post-build textbox where you can paste the script. This is important because the xml file should be in the app_data folder of the web api project that is where the help page code is searching for.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s