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 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 {YOUR_URL}/Help page.

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:

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 Build tab.

enabledocumentation1

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:

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

One Comment on “Add a documentation to your ASP.NET WebApi in 3 simple steps

  1. I followed your steps but no additional documentation appears in my help pages. How would you get the main help page where it says ‘Description: No Documentation Available’ to display something else?

Leave a Reply