Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Building ASP.NET Web API Documentation for Mere Mortals

DZone's Guide to

Building ASP.NET Web API Documentation for Mere Mortals

· Integration Zone ·
Free Resource

The State of API Integration 2018: Get Cloud Elements’ report for the most comprehensive breakdown of the API integration industry’s past, present, and future.

We are so near the end of 2014. 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

Options

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

image

In Global.asax.cs register the help page area

image

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.

image

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.

image

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.

image

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

image

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:

image

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

image

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

image

… rebuild/run your solution and Voila!

image

image

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!

Your API is not enough. Learn why (and how) leading SaaS providers are turning their products into platforms with API integration in the ebook, Build Platforms, Not Products from Cloud Elements.

Topics:

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}