The Elements of Great API Documentation
When you think of API documentation, what comes to mind? More than likely, you think of reference documentation that describes how to use an API, including the operations and request/response details. This kind of reference documentation leverages the OpenAPI Specification (formerly known as Swagger). However, there is more to documenting your API than just the reference documentation. Let’s explore the different types of API documentation and the role each has to play in helping a developer become proficient in consuming your API.
API documentation is the most important user interface for developers who will integrate your API. It acts as the primary communication medium between the API producer and the many developers who will consume the API via applications and automation scripts.
Yet, API documentation is often the least-favorite step for most developers. Within an organization, API consumers may have access to the source code to better understand how the API works. So documentation is often left off, citing access to the source code as the best way to understand how to use an API.
