What Tools Do You Use to Produce API Documentation?

By Anita Andrew | Senior Member

Over the years the IT industry has seen a significant growth in APIs that are available as free and paid services. Clearly, it is imperative to have good API documentation for developers to be able to use these APIs to develop their application, and there is a need for good documentation tools to create good API documentation.

Just like the documentation tools for any GUI-based product documentation, there is a plethora of tools available for creating API documentation as well. API documentation tools come in different flavors—automatic vs. manual, free vs. commercial, etc. This article provides an overview of some of the commonly used tools to create API documentation and also lists the criteria that can help in deciding on an API documentation tool.

Which Tool Is Suitable for My API Project?

There is no direct answer for this question as each API project differs based on the technology and language used for creating the API. Some of the criteria that can be considered for deciding the API documentation tool that suits your API project are as follows:

• Language support
• Output formats supported
• Automatic vs. manual
• Support and maintenance

Language Support

Since APIs are developed using different programming languages, the tool used for creating API documentation must support the programming language of your API project.

For example, the tool used for documenting APIs written in Java code is different from the tool used to document APIs written in .NET, PHP, or Ruby. Although there are tools such as Doxygen, NaturalDocs, HeaderDoc, Dexy, Document!X, Doc-O-Matic, etc., which support multiple programming languages and technologies, some tools support only a specific programming language or technology. For example, ApiGen supports PHP, Epydoc supports Python, Javadoc supports Java, JSDoc supports Javascript, Sandcastle supports .NET, and YARD supports Ruby, etc.

For a comprehensive list of API documentation tools and the languages they support, see Tables 2 and 3.

Output Formats

Because API users prefer documentation to be accessible easily as an on online help, the most preferred output format is HTML. However, depending on how the API documentation is used, other output formats, such as CHM, PDF, RTF, XML, Unix-Man Pages, LaTeX, etc., are also popular. Simply pick out the API documentation tool that generates your required output format. For a comprehensive list of API documentation tools and the output formats they support, see Tables 2 and 3.

Automatic Vs. Manual

Ideally, API documentation consists of an API Reference section and several conceptual sections. The conceptual sections include an introduction to the APIs, usage scenarios, example code, and other relevant conceptual topics.

Most of the API documentation tools such as Javadoc, Sandcastle, and Doxygen automatically generate the API reference section by extracting comments added to the source code. However, conceptual topics have to be created manually and later linked with the API reference section.

Some tools, such as API Blueprint from Apiary, automatically generate a template and allow you to preview the API documentation while the API is being developed. There are other tools such as I/O docs from Mashery that allow the creation of interactive API documentation, with embedded code samples and live API calls from within the API documentation.

Support and Maintenance

To leverage the features of any API documentation tool, it is essential to have good customer support for the tool in the form of user communities, discussion forums, and maintenance support in addition to good user documentation. Regular updates and releases of the API documentation tools that provide new features to support emerging technologies and fixes for issues should also be available.

A Comparison of Tools to Create API Documentation for .NET, Java, and REST APIs

The following topics provide an overview of some of the most commonly used tools to generate API documentation for .NET, Java, and REST APIs. Due to space constraints, I have limited the number of tools for each technology to a maximum of four. You can refer to Tables 2 and 3 for a comprehensive list of tools and the languages they support.

Tools for Generating .NET API documentation: Sandcastle, Document!X, Doc-O-Matic, VSDocman

• All four tools parse the XML comments added to the source code of the .NET APIs and generate API reference documentation in MSDN style format.
• Document!X, VSDocman, and Doc-o-matic can generate the API reference documentation directly from the source code, but Sandcastle needs compiled .NET assemblies for generating the API reference documentation.
• All four tools have a GUI interface that provides several customization options and also allows you to filter the members that must be visible in the final help output. For example, using the Document!X tool you can author content outside of the code and choose to override the source code comments while generating the API documentation.
• All four tools allow you to add conceptual topics such as overview, code examples, usage scenarios, etc.

Tools for Generating API documentation for Java Code: Javadoc, Doxygen

• Both Javadoc and Doxygen parse the documentation comments from a set of Java source files to produce API documentation that describe classes, interfaces, constructors, methods, and fields.
• Both tools have plugins for NetBeans and Eclipse that make it faster to generate the documentation.
• Both tools use Javadoc style comments; however, Doxygen’s comment style is more flexible as it is not heavily dependent on HTML tags for formatting the content like Javadoc is. For example, Javadoc expects the HTML tag <p> in the comments to detect paragraphs whereas Doxygen automatically detects the start of an empty line as a new paragraph.
• The Javadoc tool supports only HTML output format whereas Doxygen supports multiple output formats such as HTML, CHM, PDF, XML, RTF, and Latex.

Tools for Generating API Documentation for RESTful APIs: Swagger, I/O Docs

• The Swagger tool by Wordnik and the I/O Docs tool by Mashery are two of the most commonly used tools for documenting RESTful APIs.
• Swagger is a specification for documenting RESTful Web APIs and is language agnostic. I/O Docs is a live interactive documentation system for RESTful Web APIs and uses a JSON schema to describe APIs resources, methods, and parameters.
• The Swagger UI framework allows both developers and non-developers to interact with the API in a sandbox UI. This gives clear insight into how the API responds to parameters and options. In contrast, I/O Docs allows the user to execute API calls directly from the documentation interface, which are proxied through the I/O Docs server, producing formatted responses.

The following table lists additional tools that are available for documenting REST APIs:

Table 1. Additional tools for Documenting REST APIs

A List of Available API Documentation Tools

The following tables provide lists of free and commercial tools that are used and recommended by several API document writers in the industry.

Table 2. Freeware/Open Source/GPL/BSD Tools

Table 3. Commercial Tools

Anita Andrew is a senior technical writer on the engineering team at Talisma, a CRM company located in Bangalore, India She is a member of the STC India Chapter Anita has over 13 years of experience and has donned the hats of a technical writer, e-learning professional, programmer, and technical trainer. Her skills and interests include technical communication, API documentation, product training, process improvement, and research and troubleshooting issues related to authoring tools and technologies. She recently automated the process of API documentation generation using Sandcastle for Talisma CRM APIs. You can connect with her at in.linkedin.com/in/anitaandrew/ or at ani2005@gmail.com.