Схемы и компоненты

Schema — схема данных

Схемы AsyncAPI — надмножество JSON Schema Draft 07. Основные ключевые слова:

Группа	Ключевые слова
Тип	type (одно значение или массив, в т. ч. null), format
Строки	minLength, maxLength, pattern
Числа	minimum, maximum, exclusiveMinimum, exclusiveMaximum (числа, как в Draft 07), multipleOf
Массивы	items, minItems, maxItems, uniqueItems, contains
Объекты	properties, required, additionalProperties, propertyNames, minProperties, maxProperties
Значения	enum, const, default, examples
Комбинации	allOf, oneOf, anyOf, not, if / then / else
Описание	title, description, readOnly, writeOnly
Дополнительно (AsyncAPI)	discriminator (имя свойства), externalDocs, deprecated

components:
  schemas:
    Money:
      type: object
      required: [amount, currency]
      properties:
        amount:
          type: number
          minimum: 0
        currency:
          type: string
          enum: [RUB, USD, EUR]
    Order:
      type: object
      required: [id, total]
      properties:
        id:
          type: string
          format: uuid
        total:
          $ref: '#/components/schemas/Money'
        comment:
          type: [string, 'null']
          maxLength: 500

В отличие от OpenAPI 3.0, discriminator в AsyncAPI — просто имя свойства (строка), без mapping:

components:
  schemas:
    Pet:
      type: object
      discriminator: petType
      required: [petType]
      properties:
        petType:
          type: string

Components — переиспользуемые объекты

Поле	Содержимое
schemas	Схемы данных.
messages	Сообщения.
securitySchemes	Схемы безопасности.
parameters	Параметры каналов.
correlationIds	Идентификаторы корреляции.
operationTraits, messageTraits	Общие части операций и сообщений.
serverBindings, channelBindings, operationBindings, messageBindings	Настройки протоколов.

Имена компонентов — латинские буквы, цифры, ., -, _.

Ссылки $ref

$ref работает так же, как в OpenAPI: URI с JSON Pointer после #.

Ссылка	Куда ведёт
'#/components/messages/OrderCreated'	сообщение в этом файле
'common/schemas.yaml#/Money'	объект Money в файле из папки common
'../events/order.yaml'	весь файл целиком

В проекте «Помощника SA» пути в $ref соответствуют дереву папок проекта (относительно папки ссылающегося файла), а Ctrl+клик по ссылке открывает нужный файл и переходит к определению. Предпросмотр строит документацию по открытому файлу.

Tag и External Documentation

• Tag: name (обязательное), description, externalDocs — используется в корне, операциях и сообщениях.
• External Documentation: url (обязательное), description.

Расширения (x-)

Как и в OpenAPI, в объекты можно добавлять свои поля с префиксом x- — для инструментов и договорённостей команды: x-owner: team-orders.