Building API Documentation with Nancy and Monodevelop

I’ve got a project developing an API in C# and my development machine is Linux. This is how I integrated building the API Blueprint documentation with the Monodevelop IDE and served it using Nancy self-hosting.

Get a Template Engine

For the HTML templates, I choose Aglio. Aglio is written in Node, so you’ll need to install that first. Then use npm (bundled with node) to get Aglio. Install it globally (-g) because you don’t want a local npm package directory hanging around.

$ npm install -g aglio

Create a Doc Folder in Your Project

Create new folder called Doc at the root of your project.

Selection_093

Add Your API Document

Add the file index.md to the new Doc folder. I’ll just copy & paste the example documentation from using Apiary.io for the first time.

Selection_094

Create an Output Folder

In the View folder used by Nancy modules, add a Doc folder. This is where the generated HTML version of your API documentation will be saved.

Selection_095

Create a New Build Step

  1. Go to Project > MyAPI Options > Build > Custom Commands
  2. Select After Build Project Operation

Project Options - MyApi_097

  1. In the Command textbox, put the following text:

    aglio -i ${ProjectDir}/Doc/index.md -o ${TargetDir}/Views/Doc/index.html

  2. Click OK.

Create a README in the Output Folder

If you don’t add a file to Views/Doc and mark it Copy to Output Directory, then the folder will never be made in the folder ${TargetDir} and the post-build command will fail.

Selection_098

  1. Right-click the README.txt file
  2. Select Quick Properties > Copy to Output Directory

Build the Project and Verify the Output

Build the project and verify that the aglio tool ran and produced a index.html file in the target output directory.

Add a Nancy Module to Serve the API Documentation

At the project’s root, add a file DocModule.cs

Selection_099

Here’s a simple Nancy module to serve your generated API documentation.

Run the Project!

Run the project and you should be able to view your new API documentation at http://127.0.0.1:8888/doc

tl;dr;

Automate API documentation into your build environment using Monodevelop, Nancy, API Blueprints and Aglio. You can find the completed project on github.

One comment on “Building API Documentation with Nancy and Monodevelop

  1. Just tried this one. It’s awesome. I just wonder how I would go about building the entire doc lib. I mean I’d need to create all end points in Nancy by Hand. I wish you could just create one for Index.html and aglio would bundle everything so that from index.html you get linked to the rest of the documentation pages.

Leave a Reply