Whether you’re a startup developing your first API or an established player in the API economy, the truth is becoming steadily more apparent; providing quality API documentation is vital to the success of an API initiative. API documentation is an important part of the product offering, delivering affordances to the developer community to help them understand exactly what an API offers and how to use it.

In a recent post on the difference between API documentation, specification, and definition we clarified the role of documentation: API documentation is the part that talks to human beings, providing cognizance of your API for the developer community through explanation, samples, and examples. However, there is another simple truth that every software developer knows: Everyone (well, nearly everyone) hates writing documentation and if there is a chance to take the pain away then it should be hungrily pursued.

In this post we therefore sate the hunger by looking at the easiest ways to generate documentation for an API; regardless of a developer’s opinion on creating documentation, having a mechanism available for generating API documentation that keeps pace with the iterative nature of design and development will both reduce the workload and also allow API providers to get to market more quickly with their APIs. However, before diving into the possibilities it is worth exploring what exactly API documentation should deliver to a developer community.

What API Documentation Should Contain

There are, of course no standards or hard-and-fast rules on what API documentation should encompass; as a general rule, whatever resonates with the developer community and makes it easy for them to understand an API is a good starting point. However, there are some general themes that are backed up by examples from established providers in the API economy:

• A list of the resources with an explanation of the purpose of each in the context of the product or service being offered via the API;
• Examples of API calls in a variety of languages and tools (cURL, Postman collections, etc.);
• Guides that detail the workflows implicit in using the API i.e. the sequence of API calls that do something meaningful in the context of the product or service the API offers. For example, Dwolla offers several guides on how to send or receive money, with branches into different contexts throughout that explain the different aspects of their product offering;
• An overview of the design principles adopted by the API provider and what that means for aspects adherence to REST (especially hypermedia), HTTP codes, etc.;
• Information on authentication, including schemes that may be implemented such as OAuth or OpenID Connect;
• General information on error handling with information on the HTTP return codes that will be returned;
• User-specific contexts that help developers get to grips with the subject matter more easily. For example, Stripe automatically tailors their API documentation wth your API key and secret (when you are logged in) so any code samples are immediately ready to use;
• An interactive API explorer that allows the developer to readily bring all this information to life.

API-first Design

Regardless of the specific frame an API provider chooses to adopt, the starting point for creating API documentation is typically a well-constructed API specification document: This is especially pertinent when using an API-first design methodology where the specification tends to be an output of the process. The specification not only forms an important product for delivering the API but can serve as an input to generating API documentation, forming the backbone of the content; many of the approaches discussed below use the API specification document in exactly this way.

It therefore stands to reasons that if API-first design produces an API specification before a stitch of code is written, it also allows an API provider to start the critical job of documenting their API sooner as well, accelerating the delivery of their API. Moreover, as an API provider iterates over the API specification during the design process, refining it as they gain more insight into what will make their API successful, the API documentation can keep pace and undergo a similar process of refinement. Using an API specification as the basis for generating API documentation therefore provides a number of different approaches; key amongst these are:

• Providing an interactive explorer;
• Creating static documentation;
• Delivering a mixture of both, perhaps through the use of an API management solution.

Interactive Explorers

It is increasingly common for API specification formats to be complemented by interactive explorers generated from the specification document itself, creating a means for consumers to both learn about and test API calls at the same time. If an interactive explorer helps developers understand a provider’s API, then publishing one is a no-brainer; the options are therefore largely dictated by the choice of API specification format, for example:

• The OpenAPI Specification (aka Swagger) offers Swagger UI, which allows you to generate an interactive explorer with virtually no coding (depending on the completeness of your Swagger specification);
• Apiary offers an explorer that is generated from API Blueprint and Swagger specifications. It mixes the features of an interactive explorer with a documentation suite as it renders the Markdown documentation in API Blueprint side-by-side with an interactive tool for making sample API calls;
• Finally, an open-source explorer is offered for the RAML specification format that implements many of the same features as Swagger UI and Apiary.

These tools therefore allow API providers to very quickly create an easy-to-use reference point for their developer community. However, if the subject matter of the API is complex or requires high-level explanation not necessarily associated with a resource, static documentation may be required to accompany an interactive explorer.

Static Documentation

There is a multitude of existing tools and technologies that can help create static documentation from reference data or metadata: Middleman, Jekyll, Hugo to name but a few. However, there are also static documentation generators that focus specifically on APIs that can help reduce the overhead of creating API documentation:

• Slate is a framework that was inspired by the look-and-feel of the API documentation for Stripe and PayPal. It is used by many API providers such as Travis CI and Fidor Bank to create professional, easy to maintain documentation that can be customized and branded according to the provider requirements. There are also a number of tools that can generate core Slate documentation from an API specification document: For example, Swagger2Slate can generate Slate HTML from a Swagger document;
• There are also homegrown approaches, one of which was discussed in our earlier post on documentation-driven design which looks at a template-driven approach to creating API documentation;
• Apiary should also be mentioned in this context, given the unique twist they give to blending an interactive explorer with static documentation via the features that make this possible in API Blueprint.

Static documentation is good for getting to the meat of information. However, there are examples other than Apiary where interactive explorers and static documentation are blended. This is especially true of API management solutions.

API Management

The vast majority of API management solutions provide features and functionality that help API providers generate API documentation, combining both interactive explorers and static documentation into one package. If an API provider is using an API management solution then this can offer a convenient way of quickly delivering API documentation; however, if their API management solution does not implement an important feature and the technology is not extensible, an API provider may end up using a homegrown solution anyway. Thus, such solutions should not be seen as a silver bullet.

The exact features and functionality depends on the vendor and their view on what is important for API documentation, but it is worth exploring a few examples:

• Apigee SmartDocs is a module bundled with the Apigee Edge product that creates a model of your API, which can then be used to add documentation about the features of your API;
• 3scale implements a feature called ActiveDocs, which is based on Swagger and generates an interactive explorer hosted on 3scale. Whilst this may offer little over Swagger UI, it does provide hosting out-of-the-box so providers need not look for other solutions;
• Other products, such as Microsoft Azure API Management or the open-source Tyk gateway contain fewer capabilities for generating API documentation but still implement a CMS, giving API providers a framework for creating a rich experience for their developer community.

Final Thoughts: Customize to Dev Community

In this post we’ve looked at what creating API documentation entails and the different ways of approaching the task. As we said earlier in the post, there are no hard-and-fast standards for API documentation; many API providers implement features that are unique to them.

When implementing your own API documentation, consider the general themes and potential strategies outlined in this post, but above all create a suite of documentation that strikes a chord with your developer community. Foremost, as an API provider you should be acutely aware of what your audience is looking for as well as your unique value, so pursue the themes that feel right to you.