Как документировать асинхронное API?
#architecture #service

TL;DR Используйте AsynAPI

Упрощенно говоря существует только два способа взаимодействия: Req/Res и Pub/Sub. Еще эти способы называют синхронный и асинхронный.

При Request/Response клиент отправляет запрос на сервер, сервер начинает работу и отправляет ответ клиенту, как только работа будет выполнена. При Publish/Subscribe вместе запроса публикуется событие и ответ не требуется. Некоторые buzzword используемые при PubSub: WebHooks, Event-driven architectures, CQRS.

REST является классическим способом создания Web API и реализует Req/Res взаимодействие. Для его описания традиционно используют OpenApi, старое название Swagger.

Через WebSockets является дву-направленным протоколом, что позволяет создавать на его основе как Req/Res, так и Pub/Sub взаимодействие. Чаще всего WS используют именно для оповещений со стороны сервера, т.е для Pub/Sub. Естественно его следует описывать, использовать Documentation First подход. Для этого и был создан AsynAPI. Он позволяет описывать асинхронное взаимодействия не только по WS, но и по другим протоколам. Рекомендую к использованию.