Documentation will set you free – this is a mantra often delivered by experienced developers, and it bears repeating whenever the value of documentation is discussed. Simply put, documentation is perhaps one of the most important elements of effective API developer communication, second only to active demonstrations, tutorials, and other interactive systems. Even then, in the best of implementations, those systems actively draw from the documentation generated by the developer, thereby providing an ever greater value.
It’s unfortunate, then, that not all documentation is created equal. While the value of documentation is well-known, the way in which documentation is created is as varied as the API industry itself. This is especially evident once you move out of the classical RESTful APImicroservices industry and into other types of API design trends. Today, we’re going to be reviewing a tool called AsyncAPI that has arisen from this very clear reality.
Created by previous Nordic APIs speaker Fran Méndez, AsyncAPI fills a gap between machine-readable documentation syntax for general APIs and the message-driven architectural design that still drives a wide range of services and systems. With this in mind, what exactly is AsyncAPI? What does it do, and more importantly how does it do it?