This post will be to continue putting in place some of the plumbing for the MotorDB application.
In previous post I created a RESTful web service to return policy data to the client.
As this could be seen as a public API, it should be documented so that anybody consuming the service, will know how to use it.
When the WebAPI was released, the ASP.NET Web API, released the Microsoft ASP.NET Web API 2 Help Page 5.0.0
This Help Page will be utilized to create the documentation.
Installation
With Visual Studio running, from the Package Manager console enter:
Install-Package Microsoft.AspNet.WebApi.HelpPag
If you are using the Manage NuGet Packages dialog, search for HelpPage
At the time of this post, this will install version 5.
Once the install has been completed, then several new files and folders under Area are created
Viewing the API help pages
If you run the application, and navigate to /help, the basic layout is displayed
And clicking on a link will display information about the api.
The layout is basic as there is no styling been applied. If you review Areas\HelpPage\Views\_ViewStart.cshtml, the layout it uses is : ~/Areas/HelpPage/Views/Shared/_Layout.cshtml
All that is contained within this master page is:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width" />
<title>@ViewBag.Title</title>
@RenderSection("scripts", required: false)
</head>
<body>
@RenderBody()
</body>
</html>
To keep the site consistent, modify the layout location from
Layout = "~/Areas/HelpPage/Views/Shared/_Layout.cshtml";
to
Layout = "~/Views/Shared/_Layout.cshtml";
Once that has been done, when you refresh the help page, the api will now have the look and feel similar to the rest of the site.
However, there is no content displayed for the API. To generate help, you must use the XML Documentation Comments
There are several steps that are required to get the Help to use the xml comments.
For the UI project properties, On the build tab, enable XML Documentation file. Set the filename to App_Data\UI.xml
Open file HelpPageConfig.cs. To the Register method add the following command:
config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/UI.xml")));
If the solution was built now, because the projects are now expected to output XML, warnings are generated “Missing XML comment for publicly visible type or member”
As this is a warning, they can be ignored, however because the solution is now generating XML comments, and we are going to use them to produce documentation for the API, its good practice to resolve these warnings, especially on the ApiController and Model classes.
Next add the XML Comments to the PolicyController
/// <summary>
/// Get a list of all policies
/// </summary>
/// <returns>List of <see cref="Policy" /> objects</returns>
public HttpResponseMessage Get()
{
....
}
/// <summary>
/// Get an individual policy based on the policy identifier
/// </summary>
/// <param name="id">Required Policy Identifier</param>
/// <returns>Returns a <see cref="Policy"/> object</returns>
public HttpResponseMessage Get(int id)
{
....
}
Run the solution, now our custom comments are being displayed:
Note
There appears to be an issue when using StructureMap with the WebAPI Help Page.
In Visual Studio, if your Exceptions are set to break on “Common Language Runtime Exceptions”, then you will an Activiation Exception when you access the API Help Pages when running in debug mode. If you continue, then the API pages are being displayed correctly.
This does appear to be a known issue as it has been reported on the github repository for StructureMap Error when used with Web API Help Page package and on stackoverflow StructureMap Exception after adding the WebApi.HelpPage to a webApi project
The code has been pushed to github. Unfortunately, using TypeScript and Visual Studio 2013 has broken the build process on appharbor, so unfortunately I don’t have a running copy of this solution yet.
The error that is being generated is :
error MSB4019: The imported project “C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\v11.0\TypeScript\Microsoft.TypeScript.Default.props” was not found. Confirm that the path in the declaration is correct, and that the file exists on disk.
As soon as I get this resolved, I will update the solution.
My musing about anything and everything
The Software Dude 
[…] This post is a continuation of my previous post Documenting the WebApi using Microsoft ASP.NET Web API 2 Help Page […]
[…] Documenting the WebApi using Microsoft ASP.NET Web API 2 Help Page […]
[…] https://thesoftwaredudeblog.wordpress.com/2013/12/02/documenting-the-webapi-using-microsoft-asp-net-w… […]
Using either
Layout = “~/Views/Shared/_Layout.cshtml”;
or
Layout = “~/Areas/HelpPage/Views/Shared/_Layout.cshtml”;
The /help page only shows 6 methods out of the 12 I have in each controller. where can I change it to show all of them?
Not really sure what the problem could be.
As the documentation is running off the generated XML file, I would inspect the content of the file to see if every method is in the file.
The XML does contain the 11 or so methods.