Quick Guide: Microsoft Web Api Help Pages Populating Description

Posted: 2015-03-18 in My Opinion

A quick guide on how to populated “Description No documentation available.” in Microsoft Web Api Help Pages

Microsoft’s Web Api Help Pages is a nice surprise when it comes to something as tedious as documentation. Unfortunately it requires a small configuration to get the most out of it. This guide is a rapido guide for getting the “Description No documentation available”.

In the example I use the stock WebApplication1 generated by Visual Studio when you select a new WebApi Project.

0) Create a new ASP.NEt project and select Web API. This will create a new project with the Nuget package “Microsoft ASP:NET Web Api 2.x Help Pages”.

1-NewWebApi

1) Build and run your new project and navigate to the auto generated documentation.
You will notice the Description tags are not complete and the documentation is rather bare.

2-WebApiHelpPAgeDefault

2) Open the ValueController, go to any function and add a quick comment (type “///” to autogen).

The comments on public members, functions, and classes are used by Help Pages to generate the comments.

Add in a brief description. See image under step 5.

3) Bring up the WebApplication1 (web project) properties page (right click -> properties).

Click on the Build ->  output -> “XML documentation file:”.
Change the default value to “bin/XmlDocument.xml”

3-EnableXmloDocumentation

4) Open HelpPageConfig.cs file. This is found under ->Areas->App_Start -> HelpPageConfig.cs

Uncomment the line that mentions XML documentation. It should be one of the first lines in the public static void Register(HttpConfiguration config) function and should look something like.

MAKE sure you update path to match the path used in step 3) E.G (~/bin/XmlDocument.xml)

public static void Register(HttpConfiguration config)
{
//// Uncomment the following to use the documentation from XML documentation file.
config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/bin/XmlDocument.xml")));

....

}

5) Run the WebApi again and go to the API link. Two documentation areas should reflect you code comments.
The summary page, and the function information page.

4-TheResult

You can also add comments to the POCO classes, enums, and the controller. All are shown.

6) Optional

Stop errors due to “warnings as errors” for the warning “missing xml”

Edit the csproj file add the below after treatwarningsaerrors xml tag (note 612 and 618 are for obsolete method warning)

<WarningsNotAsErrors>1591,612,618</WarningsNotAsErrors>

If you don’t want them as build warnings then add this line as well

<NoWarn>1591</NoWarn>

7) Optional

To fix the Web API layout edit the _ViewStart.cshtml page found in the areas -> HelpPAge-Views_>Shared and replace the Layout

Layout = “~/Views/Shared/_Layout.cshtml”;

 

This is just the surface of Web Api Help Pages, you can do a lot more, including custom example generator, but that is for another day

Cheers

Choco

Advertisements

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