AsyncAPI — Swagger для брокеров сообщений и не только, или Если хочется иметь структурированную доку по асинхрону

В мире интеграций REST API на сегодняшний день занимает по праву свое почетное, королевское место. Сегодня мало какой проект или продукт обходится без стандартных HTTP-методов и документации к ним.

Но если для REST API уже всемирную славу приобрел Open API со своей Swagger-документацией, которая внедряется практически повсеместно и является по праву, так сказать, золотым стандартом, то для брокеров сообщений и, в целом для асинхронного взаимодействия, в большинстве случаев дела обстоят далеко не так однозначно.

В данной статье я хотел бы подробнее остановиться на довольно молодом типе спецификации для асинхронного взаимодействия - AsyncAPI, который, на мой взгляд, имеет огромный потенциал и все шансы на массовое применение в будущем.

На некоторых порталах, в том числе и здесь, уже косвенно поднималась тема AsyncAPI и вызывала у авторов, как правило, смешанные чувства. Описывали преимущества и недостатки, приводили некоторые примеры. Справедливо отметить, что AsyncAPI, конечно же, не идеален.

Но если посмотреть на это с другой стороны: удобно ли будет разработчику читать ТЗ и другую документацию касаемо разработки интеграции по асинхрону, слепленную из кусков текста, таблиц, рисунков, непонятных ссылок и т.д.? Одно дело, если разработчик находится на проекте с самого начала и знает все тонкости и может сам что-то додумать. Но если человек придет на проект уже через один, два или более лет после начала проекта и увидит тонны макулатуры, которую как-то нужно читать и анализировать, то вот тут начинаются трудные времена.