Visual Studio Toolbox

Web API Documentation Tools

A look at some of the tools available to automate the creation of documentation for your Web API.

• By Terrence Dorsey
• 09/16/2014

Everyone appreciates good documentation -- when they need it, anyway -- but creating and maintaining that documentation sure feels like a chore sometimes. I've been researching Web API documentation tools for a few projects, recently, and thought you might find a roundup of current options interesting.

Traditionally, creating useful API documentation involved a lot of manual labor. The old publishing problems are for the most part behind us -- online documentation has been the standard for a while, now -- and automated API extraction from your code base has been possible for more than a decade.

But, in my experience anyway, the tools available until very recently only provided a bare scaffold of your programming interface. The job of filling in any detail at all was up to your technical writers, if you were lucky and had any, or your development team if you were running lean. We could move pretty quickly through an interface's docs back in the day, but it still took time to review, write, edit and publish, even for small changes.

Today, we have a new generation of tools focused on documenting Web APIs that, frequently, integrate directly into your code base and build processes to create attractive, useful views into your API endpoints and that are always in sync with your latest code changes.

Let's take a look, with a particular focus on tools for .NET development when they're available.

ApiExplorer
If you're working with ASP.NET Web API, the first place you probably want to look for automating API documentation (and possibly testing as well) is the ApiExplorer class built right into the Microsoft .NET Framework.

Yao Huang Lin, who works at Microsoft on ASP.NET MVC and Web API, explains in his blog post "ASP.NET Web API: Introducing IApiExplorer/ApiExplorer," that "IApiExplorer is an abstraction layer that allows you to obtain a description of the structure of your Web APIs. This information can be used to produce documentation, machine-readable metadata, or a test client." Yao has a follow-up post explaining in detail the process of "Generating a Web API Help Page Using ApiExplorer."

There's also a Microsoft ASP.NET Web API 2.2 Help Page NuGet package that helps you automatically generate Web pages using ApiExplorer. This package is now included with Visual Studio as of the ASP.NET Fall 2012 Update.

For a primer on integrating automated API documentation into your ASP.NET projects using ApiExplorer and the Web API Help Page package, check out Mike Wasson's article, "Creating Help Pages for ASP.NET Web API." Yao provides a more comprehensive three-part overview and tutorial in his post, "Introducing the ASP.NET Web API Help Page (Preview)." Figure 1 shows an example.

Actually, Yao's blog is a treasure trove of information and examples for building pretty sophisticated API documentation on the fly with ApiExplorer. It's definitely worth your time to read through the archives and have your mind blown.

I also recommend reading through John V. Petersen's "Documenting Your ASP.NET Web APIs" post for some additional ideas that build upon what Yao discusses in his blog, as well as lxgnxr's Stack Overflow question, "Web API – Auto-Generating Request Samples Using ApiExplorer."

Swagger
Another option for documenting ASP.NET-based APIs is Swagger, "A simple, open standard for describing REST APIs with JSON," is really a specification for integrating doc generation into your API framework than something you can plug right in and get going immediately. (See the Wordnik Swagger spec for details.) To get a feeling for the docs generated by Swagger, play around with the Swagger UI Pet store server example, shown in Figure 2.

Building documentation with Swagger involves first annotating your service code in a manner similar to javadoc or phpdoc. Then you use a parsing and codegen module tailored to your service's programming language or framework, along with Swagger UI, to generate the interactive interface to your REST APIs.

The Swagger spec on GitHub contains links to a variety of Wordnik and third-party projects that help you with Swagger doc generation in different environments. For .NET Framework developers, check out the Swagger.Net and Swashbuckle projects for documenting ASP.NET Web API projects with Swagger. FubuMVC Swagger, unsurprisingly, provides Swagger generation support for FubuMVC-based Web apps. There's also a Swagger API for ServiceStack.

Over in the NuGet Gallery, searching for Swagger packages returned 15 results (at the time this column was written), including Swagger integrations for ASP.NET MVC 4, ASP.NET MVC 5 and OpenRastaSwagger.

RAML
RAML is a newish JSON- and YAML-based API modeling language specification. It's a "non-proprietary, vendor-neutral open spec," but you should know that MuleSoft is behind much of the current development. While there isn't any .NET-specific tooling available, I'm keeping a close eye on progress and recommend that you do, as well.

From my point of view, what's important is that, where Swagger and similar tools incorporate documentation spread out across your code base, RAML gathers your work into a central YAML configuration. However, you can also include JSON schemas from external sources as either discrete documentation or verification elements.

I'm sufficiently intrigued by the ideas here that I've even recommended further exploration by my own team. As the sole technical writer supporting a team of API developers, I definitely like the idea of managing a single config document bringing in whatever external resources we need, rather than keeping tabs on all the far-flung files within our API tier code repositories.

I'll report back in a future column if we get around to experimenting further in our dev environment.

Do You Really Need Docs?
Many discussions of Web APIs get hung up on the finer points of REST APIs and whether a given RESTful API actually follows REST principles. For the record, I set out to find a good example of someone categorically stating that REST APIs are self-documenting and failed.

Instead, I came across a very interesting Stack Overflow question. While the question and answers shed some useful light on REST in theory and practice, my technical-writer mind focused on this particular sentence: "API documentation should focus on explaining how to interpret the hypertext contained in the response." Or, put more clearly by commenter redben, "The thing that most people get wrong is that (at least I think) in the REST world you don't document your 'REST interface,' what you document is a media type, independently of your server or service."

In other words, how developers can call your API is only one part of the problem. It really comes down to two questions that define your API: What endpoints can we call, and what verbs -- GET, PUT, POST or DELETE -- can we call on them? All of the tools I've discussed here should be able to help you do that quickly, clearly and automatically.

What's equally important is making sure your media type is clearly documented. Not just whether it's XML or JSON, but what it provides and what it means for developers trying to consume or interact with your API. This is more difficult because, typically, it can't be done in an entirely automated fashion.

By the way, an often-cited example of a well-documented REST API is the Project Kenai Sun Cloud Wiki.

I hope you GET enough knowledge from this column to PUT better docs online for your API, with far less effort than you expected.

• Get Code Download