Documenting the WebApi using Microsoft ASP.NET Web API 2 Help Page

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

helppage

Viewing the API help pages

If you run the application, and navigate to /help, the basic layout is displayed

HelpPage_Index

And clicking on a link will display information about the api.

HelpPage_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:

HelpPage_Index2

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.

Advertisements

My musing about anything and everything

Tagged with: , , ,
Posted in Help Page, MotorDB, Visual Studio, WebAPI
6 comments on “Documenting the WebApi using Microsoft ASP.NET Web API 2 Help Page
  1. […] This post is a continuation of my previous post Documenting the WebApi using Microsoft ASP.NET Web API 2 Help Page […]

  2. […] Documenting the WebApi using Microsoft ASP.NET Web API 2 Help Page […]

  3. Ofer Gal says:

    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?

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

Enter your email address to follow this blog and receive notifications of new posts by email.

Join 9 other followers

%d bloggers like this: