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
OptionsSince 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:
Setting upIn 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!