Документация / AsyncAPI

Введение

AsyncAPI — спецификация для описания событийных (асинхронных) API: какие сообщения приложение отправляет и принимает, через какие каналы брокера (Kafka, RabbitMQ, MQTT, WebSocket и др.), в каком формате и как защищены подключения. Это то же, что OpenAPI для HTTP, но для обмена сообщениями.

asyncapi: 2.6.0
info:
  title: Сервис заказов
  version: 1.0.0
channels:
  orders.created:
    subscribe:
      summary: Сервис сообщает о новом заказе
      message:
        payload:
          type: object
          properties:
            orderId:
              type: string
              format: uuid
            total:
              type: number

Термины

Приложение — любая программа, которая отправляет или принимает сообщения: сервис, клиент, скрипт. Документ AsyncAPI описывает одно приложение — его сообщения и каналы.
Производитель (producer) — приложение, которое отправляет сообщения; потребитель (consumer) — которое принимает. Одно приложение часто бывает и тем и другим.
Сообщение — данные, передаваемые через брокер: заголовки и полезная нагрузка (payload). Сообщение может быть событием («заказ создан»), командой («отправь письмо») или запросом.
Канал — адресуемое место в брокере, через которое передаются сообщения: топик Kafka, очередь или маршрутизирующий ключ RabbitMQ, топик MQTT, путь WebSocket.
Протокол — способ обмена: kafka, amqp, mqtt, ws, http и другие.

Редактор в «Помощнике SA»

Спецификация пишется слева в YAML или JSON, справа — документация, построенная официальным компонентом AsyncAPI; ошибки проверки спецификации показываются в предпросмотре.
Поддерживаются версии 2.x (эта документация описывает 2.0 с уточнениями последующих версий 2.x) и 3.0 — отличия описаны в разделе «AsyncAPI 3.0».
Ctrl+клик по $ref переходит к определению в этом или другом файле проекта; кнопка «ИИ-ревью» проверяет спецификацию по лучшим практикам (тарифы «Макс» и выше).

Формат документа

Документ AsyncAPI — JSON-объект, записанный в JSON или YAML 1.2. Имена полей чувствительны к регистру. Поля description поддерживают разметку CommonMark. Документ может ссылаться на другие файлы через $ref.

Схемы и JSON Schema

Схемы сообщений в AsyncAPI по умолчанию записываются на надмножестве JSON Schema Draft 07: работают type, properties, required, items, enum, oneOf, allOf, format и т. д., а также добавлены свои поля (discriminator, externalDocs, deprecated). В отличие от OpenAPI 3.0, type может быть массивом, а null — обычным типом.

Документация основана на спецификации AsyncAPI 2.0.0 (лицензия Apache 2.0), переведена и сокращена; уточнены места, которые чаще всего понимают неправильно (смысл publish и subscribe).