Add a documentation to your ASP.NET WebApi in 3 simple steps

A well documented API is a welcome part of every software project. Everyone wants a great documentation, bot nobody really wants to write one. Especially when creatingan API whichmany different people should use, this aspect becomes very important. Furthermore many Scrum teams’ acceptance criteras contain a documentation requirement.

Your luck, that ASP.NET 4.5 comes with a build in API-Documentation functionality that you can implement in three very easy steps:

1. Add build-in ASP.NET WebApi Documentation

Microsoft provides a build-in documentation functionality with its WebApi. When creating a new WebApi Project in Visual Studio, the template already contains a documentation implementation. If you created the WebApi project from scratch, you can add it by loading the NuGet packageMicrosoft.AspNet.WebApi.HelpPageinto your project.

Both ways will create an Areas/HelpPagefolder, which contains a bunch of methods and classes that will do the documentation work for you. From now on you can access your documentation at the {YOUR_URL}/Help page.

2.Document your codeproperly

The smartest way to document your methods and classes in C# is the XML-Documentation approach, that comes with .NET 4.5.This documentation style looks like this in your code:

<code class="language-csharp">/// <summary>
/// Register a new user to to application
/// <summary>
/// <param name="registration"> Registration model that provides a username and password</param>
/// <returns> Feedback about the success of the user creation&l</returns>
public IHttpActionResult Register(Registration registration)
    // ...

**Hint:**You can generate this XML-Documentation header by typing three slashes ///above a method or class.

By using this way of documentation, you do not only create a documentation for your Help page. This informationis also used inside of Visual Studio to describe a method and its parameters when using code completion and Intelly Sense.

3. Enable documentation access

Togive your Help page access to this documentation you need to enable the XML-Documentation output. By doing this, every time you build your project an XML file isgenerated that contains your documentation comments. To enable this, you need to select the proper checkbox in the project properties, that you can find at the Build tabenabledocumentation1

**Hint:**By enabling the XML-Documentation output, the compiler will send you a warning for every method or class that is undocumented. If you want to avoid that, add 1591 to the suppressed warnings as you can see in the screenshot above.

Now you only need to tell your HelpPage that you do have such a file and where it is located. To do so, open the HelpPageConfig.cs file, uncomment the following line and edit the MapPath:

<code class="language-csharp">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/XmlDocumentation.xml")));

    // ...

Now you are ready to enjoy a fully featured documentation of your ASP.NET WebApiat the `{YOUR_URL}/Help` page.