What is ApiDoc

ApiDoc is a tool for creating a set of technical API documents to help developers using your libraries or classes.

As a .NET developer you’ve probably used the MSDN references for various .NET classes on a regular basis.  But how do you make the same style of documentation available to your team or users of your libraries from other companies?

This article shows you how to use ApiDoc to generate MSDN style API documentation for your own classes, in a way that is easy to customise, integrate with existing websites, and can have your own branding applied.

Getting ApiDoc

To get started you need to download ApiDoc.  You can do this from codeplex: apidoc.codeplex.com.

The download includes full source code for ApiDoc and a fully functional demo website you can use and customise.  We’ll use this demo website in this article so be sure to download and extract the .zip file to a location you can edit it.

In the future if you want to you could add ApiDoc to your existing ASP.NET site or application via NuGet instead (see ApiDoc and ApiDoc.Mvc4).

Getting Started

Once you’ve downloaded and extracted the .zip file open the “ApiDoc.sln” in Visual Studio.

To run the demo site make sure the ApiMvcApplication is set as the start-up application and press F5.

By default the site is configured to show the documentation for the ApiDoc library itself.  Have a browse around and you will be able to browse through around the documentation jumping from class to class as easy as you can with the MSDN.

Documenting your own Code

The next step is to get the demo site working with your own code.  Close the web browser and stop debugging the program so you return to Visual Studio.

Under the ApiMvcApplication expand the Content folder and you will find an “AssembliesToDocument” folder:

Using explorer to find the .dll files and associated .xml files for your application and drag and drop them into AssembliesToDocument so they show in the list.

Now open HomeController.cs under Controllers and you’ll see the following:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;

namespace ApiMvcApplication.Controllers
{
    public class HomeController : Controller
    {
        public ActionResult Index()
        {
            return RedirectToAction("Namespace", "ApiDocumentation", new { id = "ApiDoc" });
        }
    }
}

The important part here is line 13. You can modify it to match the namespace you want to be your start page by changing id = “ApiDoc” to your own namespace e.g.:

            return RedirectToAction("Namespace", "ApiDocumentation", new { id = "MyApplication" });

You may prefer to open to the index of an assembly:

            return RedirectToAction("Assembly", "ApiDocumentation", new { id = "MyClassLibrary1" });

or directly to your main class:

            return RedirectToAction("Type", "ApiDocumentation", new { id = "MyApplication.MyMainClass" });

Hit F5 again and this time you will see the documentation for your own code rather than for ApiDoc itself.  You can navigate this code exactly as you could before.

Customising the Web Pages

The demo site is a standard ASP.NET MVC 4 site using C# and the razor syntax.  This means if you know how to create standard web applications in this environment customising the site to meet your needs will be very easy.

The views can be found in the default place under Views/ApiDocumentation.  Here you can change the order of documented items, apply custom scripts, or apply your own logic to the API or documentation as you display it.

To customise the style of the site you can edit “Content/Site.css”.  The site uses the standard classes from the MVC project templates, but you can customise specific divs in the views using their member names e.g. “description”, “classes”, or “properties”.

The ApiDocumentation controller can be found under “Controllers/ApiDocumentation.cs” and has a separate action for each member type making it easy to customise or extend.

To make the demo site look nice I’ve used the SyntaxHighlighter scripts to format the code syntax examples in the same way code samples are highlighted on this blog.  If you are customising the demo site for your own purposes you just need to reference the code within a pre block as follows to have the syntax highlighting take place:

    <pre class="brush: csharp">
        @Model.CodeDefinition
    </pre>

You should now know everything you need to know to document your own libraries in your own style. If you’d like a link to your library documentation added to the ApiDoc project on Codeplex drop me an email with the link and brief description so I can add it to the site.

Getting Involved

ApiDoc is available under a BSD style license for everyone who needs to generate custom Api Documentation. Its currently Beta software and may contain a few issues which should be pretty easy to sort out and will be fixed as new versions of the library are released. If you want to get involved with the project itself please visit the Codeplex page where all feedback, bug reports, and suggestions are welcome through the discussion pages, and anyone wanting to contribute directly to the project will be invited to do so.