Tuesday, December 1, 2015

Using Xml Comments for ASP.NET Web API Help Pages

I had recently installed the Help Page NuGet package for my ASP.NET Web API project (https://www.nuget.org/packages/Microsoft.AspNet.WebApi.HelpPage/) but I noticed that none of my Xml Comments were appearing in the Web API Help Pages!

Well, fortunately, I came across this article: http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages

I discovered there was a line in HelpPageConfig.cs under the HelpPage Area (Areas/HelpPage/App_Start/HelpPageConfig.cs) that was preventing the Xml Comments from appearing in my Web API Help Pages!
config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

I found this code on line 37 of my HelpPageConfig.cs file in the Register method.

I also discovered that the Xml Documentation file path could be either: App_Data/XmlDocument.xml or App_Data\XmlDocument.xml, though App_Data\XmlDocument.xml is the common document file path on Windows machines.

Once I followed the guidelines outlined in the article to use Xml Comments as well as ensuring that my project was generating and outputting Xml Comments to the correct location, I could view my Xml Comments in my Web API Help Pages!

Unfortunately, my C# Xml Comments only served to provide some partial documentation since it did not cover all of the other areas that were required in the Web API Help Pages, however, it was a good starting point to documenting my ASP.NET Web API methods!

No comments:

Post a Comment