Recently I’ve been building an API for work with the new ASP.Net Web API features and needed to document the functionality for 3rd Party users. I defaulted to cranking open Word and started typing, but it felt clunky. As soon as I started to create a table to track version history I started to foresee the confusion often caused in keeping the documentation in sync with the version of the API. Add to that the API is likely to be used on multiple customer sites which may not all be on the same version of the software and there is a recipe for issues in the future.
I decided instead to opt for web based documentation built into the API to ease the potential for syncing issues. I previously posted about my new-found love of Markdown for simplifying publishing for this blog and whilst there are loads of wiki packages out there I opted for a simple Markdown based solution. Fortunately there’s already a Nuget package available to aid with this: Kiwi.Markdown.
To include in a Web API project (I’ve assumed the Razor view engine) you can start by using the Package Manager console:
PM> Install-Package Kiwi.Markdown
to keep it nicely formatted I also threw in Twitter Bootstrap:
PM> Install-Package Twitter.Bootstrap
The Kiwi.Markdown package creates a new view for you for formatting the Markdown.
By default this file will be picking up its layout from:
To incorporate Bootstrap into your Markdown pages, change _Layout.cshtml to:
and your Doc.cshtml to:
Now adding md files to:
will result in nice neatly formatted good looking documentation.