Сообщения

Message — сообщение

Поле	Описание
`headers`	Схема заголовков сообщения (тип `object`).
`payload`	Схема полезной нагрузки.
`correlationId`	Где в сообщении находится идентификатор корреляции.
`schemaFormat`	Формат схемы `payload`, если это не схема AsyncAPI (например, Avro).
`contentType`	Тип содержимого; по умолчанию — `defaultContentType` из корня.
`name`	Машиночитаемое имя сообщения.
`title`	Название для людей.
`summary`, `description`	Краткое и подробное описание.
`tags`, `externalDocs`	Теги и внешняя документация.
`bindings`	Настройки сообщения для протокола (например, ключ Kafka).
`examples`	Примеры: объекты с `headers` и `payload`.
`traits`	Общие части сообщений (Message Trait).

asyncapi: 2.6.0
info:
  title: Сервис заказов
  version: 1.0.0
channels:
  orders.paid:
    subscribe:
      message:
        $ref: '#/components/messages/OrderPaid'
components:
  messages:
    OrderPaid:
      name: OrderPaid
      title: Заказ оплачен
      summary: Отправляется, когда платёж по заказу подтверждён
      contentType: application/json
      correlationId:
        description: Идентификатор исходного запроса
        location: $message.header#/correlationId
      headers:
        type: object
        required: [messageId, correlationId]
        properties:
          messageId:
            type: string
            format: uuid
          correlationId:
            type: string
            format: uuid
      payload:
        type: object
        required: [orderId, amount, paidAt]
        properties:
          orderId:
            type: string
            format: uuid
          amount:
            type: number
            minimum: 0
          currency:
            type: string
            enum: [RUB, USD, EUR]
            default: RUB
          paidAt:
            type: string
            format: date-time
      examples:
        - headers:
            messageId: 2f1c5d0e-7a1b-4c3d-9e4f-000000000001
            correlationId: 9b2d7f40-1c3e-4a5b-8c6d-000000000002
          payload:
            orderId: 5f0c2b1e-8d4a-4c1e-9b7a-2f6d3e1a0c42
            amount: 1590
            currency: RUB
            paidAt: '2026-10-01T12:30:00Z'

Correlation ID

Идентификатор корреляции связывает сообщения одного обмена — например, запрос и ответ или цепочку событий.

Поле	Описание
`description`	Описание.
`location`	Обязательное. Выражение: `$message.header#/путь` или `$message.payload#/путь`.

Несколько сообщений в канале

Если в канал отправляются сообщения разных видов, они перечисляются через oneOf. Потребителю нужно различать их — удобно по имени в заголовке или полю-дискриминатору в payload.

channels:
  orders.events:
    subscribe:
      message:
        oneOf:
          - $ref: '#/components/messages/OrderCreated'
          - $ref: '#/components/messages/OrderPaid'
          - $ref: '#/components/messages/OrderCancelled'

Схемы в других форматах

schemaFormat позволяет описать payload схемой другого формата — например, Avro для Kafka:

components:
  messages:
    OrderCreatedAvro:
      schemaFormat: application/vnd.apache.avro;version=1.9.0
      payload:
        type: record
        name: OrderCreated
        fields:
          - name: orderId
            type: string
          - name: total
            type: double

По умолчанию schemaFormat — схема AsyncAPI (надмножество JSON Schema Draft 07).

Message Traits — общие части сообщений

Общие заголовки и настройки выносятся в components.messageTraits и подключаются к сообщениям через traits.

components:
  messageTraits:
    commonHeaders:
      headers:
        type: object
        properties:
          messageId:
            type: string
            format: uuid
          producedAt:
            type: string
            format: date-time
  messages:
    OrderCreated:
      traits:
        - $ref: '#/components/messageTraits/commonHeaders'
      payload:
        type: object