Building ASP.NET Web API documentation for mere mortals

December 25, 2014/POSTED BY Marjan Nikolovski/0 Comments
We are so near the end of 2014. A lot of great challenges were done with success and we are looking forward for new challenges for the next year! As this will be the last post for 2014 I wanted to write about a very interesting topic that I was solving several days ago. It is a topic about creating/generating documentation for a ASP.NET Web API.

Recently I was working on building an API for Suave, so we can create additional mobile apps and clients for our product ecosystem. In general if the project architecture is layered up correctly, developing an API is a very simple task to be done. We create the models, expose business functionalities, set the authentication and we are ready to roll.

To say that we are finished with building an API task there is one more piece left for the puzzle to be solved – API documentation. API is all about how other consumers(read developers) will utilize product business logic in their external application. As such if an API is missing a documentation, it will be a hell of a job for someone to integrate the API in their application.

Documenting existing ASP.NET Web API


Since we are living in great times where technology is progressing with fast pace we want to use that opportunity and avoid manual work while producing the documentation. What are our options you may ask?

There are several options available for automatic generation of Web API documentation. Most stable and popular are: I’ve had time to explore both of them and picked the second option due to the fact that it is easier to customize and add additional functionalities in the documentation.

Setting up

In your existing project install Microsoft.AspNet.WebApi.HelpPage


In Global.asax.cs register the help page area


If we run the solution and navigate to localhost:[POSTNUMBER]/help we should see the generated documentation. The documentation output can be easily customized by editing HelpPage/Views.


As we can see routes documentation/description is missing. We need descriptions, error types, model types and all of comments associated with the routes to be displayed in order to build an API that someone can use.

To force them to be displayed on the UI we need to configure the documentation provider. In the HelpPage area we will edit and set the default documentation provider to XmlDocumentationProvider with provided xml path.


In the build property of the project we need to setup the xml documentation file to be generated by the build process so it can be used as a documentation source for the XmlDocumentationProvider.


If we compile and run again, we should see the comments which are decorating the methods, models and model properties.


But wait! We are missing valid routes from our API. What should we do?

While struggling to discover what was causing the pain in the API explorer, I’ve stumbled upon a StackOverflow discussion where one of the users stated that there is a bug still not solved in ApiExplorer and presented a simple workaround. The code snippet was using reflection to call ApiExplorer “ExploreRouteControllers” method.

Bellow is the modified and working version of the code that we will use for getting API valid routes and descriptions:


Instead of the existing code in HelpController/Index, we will use our extension to get the API descriptions:


Last step would be to change the default API routing so it wont mask the routes:


… rebuild/run your solution and Voila!



As always, this code sample can be found on GitHub. Hope that now you can create and manage your documentation with ease!

Merry Christmas and a Happy New Year!

About Marjan Nikolovski

Co-owner, Team lead Full stack .NET and Javascript engineer, speaker and active open source contributor. Excited about Distributed programming, Software architecture, Cloud based solutions.


Leave a comment

Your email address will not be published. Please mark all required fields.

You must be logged in to post a comment.