Редактор AsyncAPI онлайн: Kafka, RabbitMQ и другие брокеры

Как описывать событийные интеграции в AsyncAPI 2 и 3: каналы, операции и сообщения с документацией справа, схемы в отдельных файлах и диаграмма обмена.

AsyncAPI делает для событий то же, что OpenAPI для HTTP: описывает каналы (топики, очереди), кто в них пишет и читает, и структуру сообщений. Редактор показывает документацию по мере набора.

Как начать

Откройте песочницу AsyncAPI — там пример событий интернет-магазина (Kafka).
Пишите спецификацию слева в YAML или JSON — справа документация: серверы, каналы, операции, сообщения со схемами и примерами.
Свой файл — Файл → Открыть файл…; скачать — Файл → Скачать в YAML или JSON.

Редактор AsyncAPI с документацией каналов — Спецификация AsyncAPI и документация каналов и сообщений

AsyncAPI 2 и 3

В 2.x операции описаны внутри каналов: publish — приложение отправляет, subscribe — получает (многих путает: это точка зрения клиента).
В 3.0 операции вынесены в раздел operations с явным action: send или receive и ссылкой на канал; адрес канала — address.
Редактор поддерживает обе версии; документ определяется по полю asyncapi.

Схемы сообщений в отдельных файлах

Схемы payload часто общие с REST API. Храните их в проекте и ссылайтесь через $ref по относительному пути — так же, как в многофайловых OpenAPI. Ctrl+клик по ссылке открывает файл.

Диаграмма обмена

Файл → Преобразовать в → PlantUML — диаграмма компонентов строит схему: приложение, каналы (очереди) внутри брокеров с протоколами, стрелки отправки и получения с названиями сообщений. Её удобно вставить в документацию интеграции.

Пример: AsyncAPI 3.0

asyncapi: 3.0.0
info:
  title: Сервис заказов
  version: 1.0.0
servers:
  production:
    host: kafka.example.ru:9092
    protocol: kafka
channels:
  orderCreated:
    address: shop.orders.created
    messages:
      OrderCreated:
        payload:
          type: object
          required: [orderId]
          properties:
            orderId: {type: string, format: uuid}
operations:
  publishOrderCreated:
    action: send
    channel: {$ref: '#/channels/orderCreated'}

Вопросы и ответы

Как перевести спецификацию 2.x на 3.0? Автоматического преобразования нет. Главные изменения: операции выносятся из каналов в operations с action, у канала появляется address, сообщения перечисляются в messages канала, servers.*.url делится на host и pathname.

Где синтаксис? В документации по AsyncAPI.