.Net Web API Help Files

Intro

Help me Rhonda, help help me Rhonda...
Sorry about that, my parents used to listen to the Beach Boys all the time in the car and that tune is pretty catchy. So I was sitting here thinking about ways to help people, and I thought of Web API help files. When you make a Web API that you want to publish for people, creating documentation can get a bit tedious. Wouldn't it be great if there was an automatic way of generating help files? Yeah you know it baby, there is such a thing! And of course, it's a NuGet package that's nice and easy to plug into your existing Web API projects in .Net. Let's see what this sucker does for us!

Note: The sample project is in Visual Studio 2013, .Net 4.5.

Usage

So the NuGet package name is Microsoft ASP.NET Web API 2.2 Help Page. Bit of a mouthful there huh?

To start off our efforts, I've created a blank Web API project in Visual Studio. I created a single controller named SampleController, with a get method that returns "hi". Here's the code for it in case you want to play along:

using System.Web.Http;

namespace BlogWebApiHelp.Controllers
{
    public class SampleController : ApiController
    {
        public IHttpActionResult Get()
        {
            return Ok("hi");
        }
    }
}

If you run the project in your browser and look at http://[baseurl]/api/sample, you'll get back a json file (or xml depending on your browser) with the word "hi".

OK time to install the Help package to see what it does for us. Open up the package manager console via Tools-->NuGet Package Manager-->Package Manager Console. Type this text into the Package Manager Console and hit Enter: Install-Package Microsoft.AspNet.WebApi.HelpPage. The package is now installed and you'll notice your solution has a new folder named Areas. There's quite a bit of content in here that's all Mvc-style, and yes you can customize it all you like. It's what generates the help pages for your API that you're about to see.

There's one more small code change you have to make in order for this stuff to work. Open up your Global.asax.cs file and put this one line in your Application_Start method:

AreaRegistration.RegisterAllAreas();

Note that you will have to add using clause for System.Web.Mvc if you don't have one already.

Let's see this little sucker in action! Fire up the Web API and navigate to http://[baseurl]/help. You should see a badass little page like this one on yer screen:

That's sweet! It found the Sample controller and is showing us that it has a Get method which we can execute by calling api/Sample. Huh, this thing doesn't have a description though? Lame! Stupid package should document my methods for me. Well it isn't quite that cool, but it's pretty close. Close the browser and head back to Visual Studio. Put an XML comment on the Get method of SampleController. There's a small code change you have to make too. Open up the file Areas\HelpPage\App_Start\HelpPageConfig.cs. In here you need to uncomment this line:

config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

As you can see, this line tells the Help package that it should look for a file within your web app named XmlDocument.xml within the app_data folder. We haven't created any such file so let's tell our project to autogenerate that xml file for us. Right-click on your project and open up the Properties window. Check the checkbox next to "XML documentation file:", and for the name type "bin\XmlDocument.xml". Save.

Run this thing again and open up the help url. Aww yeah baby, our XML documentation is now our Web API Help file documentation! It doesn't get much better than this folks. You can put documentation on methods and classes, it will pick up parameter documentation, and you can style these pages as you like. Awesome!

What's Next?

Try creating your own Web Api with help files, or download the source code from the link above and play with mine. Open up the two links below in the Resources section and see what other features this thing has. Tip: you can hide methods and controllers from the API documentation!

Resources

Microsoft ASP.NET Web API 2.2 Help Page
Creating Help Pages for ASP.Net Web API

Documentation

One day in your coding career (preferably early) you'll reach the point of:  I wrote this weird thing  and for the life of me can't recall what I was attempting to accomplish.  Where'd I go wrong?  What could I have done back then that would've saved me countless hours in the future?  Document your code!

Techniques:

Chances are if you went to college to learn to write software they may have emphasized self-documenting code (aka naming your for loop variable i or x when looping through a list of table rows you could've named the variable rowIndex or something more definitive).  If not, it's a great idea to try to implement self-documenting coding techniques.  Your present and future colleagues will appreciate you more for that one.

Another option is to put in the occasional comment or two.  Generally speaking if I can't rationalize what an obscure block of code is doing (happens quite a bit out in the wild) I throw in at least some documentation on what that block of code is attempting to do.  That way future me and present me can be on the same page quicker than not so future me can determine what action to do next to it more efficiently than if it the coding block wasn't documented.

The last option is putting your pseudo-code into comments near your obscure block(s) of code.  If nothing else future you (or your colleagues) can try to see what present you was attempting to do in the source code.  This form of documentation is one I've been trying to implement in the past six months or so, so far I've used it a few times when the self-documenting code as well as the comments for each block might now give future me (or a colleague) an idea of what present me was attempting to create.

Conclusions

Documenting your code might seem like a bit of a hassle but in the long term it'll save future you (and potentially your colleagues) time to debug/determine what your present code is doing.

Shout outs:

I have to give credit to Peter Hyde and Bobby Russell for blogging along for quite some time now, keep up the great work guys!