A good API is often accompanied by bad documentation which makes adoption confusing and slow. In this article I will discuss how to produce great documentation for your APIs.
This article is part of the ‘Essentials’ series and focuses on the ground-level understanding required to undertake the journey in to the world of APIs and will through the course of the series build upon your skills and introduce you to core concepts. This series is intended for people who wish to gain a rudimentary understanding of APIs such as students, new software developers and managers wishing to gain understanding and experience within their team.
It is astonishing to think about what happens in corporate software development divisions. If there is any adherence to a life cycle I can only imagine the amount of planning, meetings, scrums and sprints as well as the endless cycles of tests required to produce a quality API. Yet when released and made available for use the API is quite often supported by confusing, unclear and lackluster documentation.
Software developers and integrators need to understand your API. The worse the documentation the more you rob your partners and developer community of essential knowledge and understanding with which to appreciate your API.
In this article I will base the task of producing quality documentation upon two competing standards. Whilst there are others available I have selected and used these standards for their abilities to provide an easy system with which to produce and render the documentation as well as their abilities to support multiple programming languages.
Based on the requirements above I generally use Swagger and API blueprint as my most prominent documentation frameworks. However for the purposes of this ‘Essentials’ article and to get our feet wet in the concept of live documentation I’ll be focussing on the most prominent standard being Swagger.
Up Next: What Is Live Documentation?