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 creating an API which many 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 package Microsoft.AspNet.WebApi.HelpPage into your project.
Both ways will create an
Areas/HelpPage folder, 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
2. Document your code properly
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:
/// Register a new user to to application
/// <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 information is also used inside of Visual Studio to describe a method and its parameters when using code completion and Intelly Sense.
3. Enable documentation access
To give 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 is generated 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
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:
public static void Register(HttpConfiguration config)
// Uncomment the following to use the documentation from XML documentation file.
Now you are ready to enjoy a fully featured documentation of your ASP.NET WebApi at the