Схемы данных

Schema Object описывает структуру данных: объекты, массивы, примитивы. В OpenAPI 3.0 это расширенное подмножество JSON Schema (черновик Wright 00): часть ключевых слов взята без изменений, часть — с уточнениями, и добавлены свои (nullable, discriminator, readOnly, writeOnly, xml, example, deprecated).

Ключевые слова

Группа	Ключевые слова
Тип	type (string, number, integer, boolean, array, object), format, nullable
Строки	minLength, maxLength, pattern (регулярное выражение ECMA-262)
Числа	minimum, maximum, exclusiveMinimum, exclusiveMaximum (логические в 3.0), multipleOf
Массивы	items (обязательно при type: array), minItems, maxItems, uniqueItems
Объекты	properties, required, additionalProperties, minProperties, maxProperties
Значения	enum, default
Комбинации	allOf, oneOf, anyOf, not
Описание	title, description, example, deprecated, externalDocs
Направление	readOnly (только в ответах), writeOnly (только в запросах)

Важные отличия от JSON Schema в 3.0:

• type — одно значение, а не массив; значение null задаётся не типом, а nullable: true;
• items должен быть схемой, а не массивом схем;
• exclusiveMinimum / exclusiveMaximum — логические флаги к minimum / maximum;
• рядом с $ref остальные ключевые слова игнорируются (для уточнения используйте allOf).

Объект

components:
  schemas:
    Order:
      type: object
      description: Заказ интернет-магазина
      required: [id, status, items]
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        status:
          type: string
          enum: [NEW, PAID, SHIPPED, CANCELLED]
          default: NEW
        comment:
          type: string
          nullable: true
          maxLength: 500
        total:
          type: number
          minimum: 0
          example: 1590.00
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/OrderItem'
        createdAt:
          type: string
          format: date-time
          readOnly: true
      example:
        id: 5f0c2b1e-8d4a-4c1e-9b7a-2f6d3e1a0c42
        status: PAID
        total: 1590.00
        items: [{ sku: A-1, qty: 2 }]

required перечисляет обязательные свойства; свойство может быть обязательным и при этом nullable. readOnly: true у обязательного свойства означает, что оно обязательно только в ответах.

Словари: additionalProperties

additionalProperties описывает свойства, не перечисленные в properties. Так задаются словари «ключ → значение»:

components:
  schemas:
    PricesByRegion:
      type: object
      description: Цена по коду региона
      additionalProperties:
        type: number
      example:
        msk: 990
        spb: 950

По умолчанию additionalProperties разрешает любые дополнительные свойства; additionalProperties: false запрещает их.

Композиция: allOf, oneOf, anyOf

• allOf — значение соответствует всем схемам (расширение, наследование);
• oneOf — ровно одной из схем;
• anyOf — хотя бы одной;
• not — не соответствует схеме.

components:
  schemas:
    BaseEntity:
      type: object
      required: [id]
      properties:
        id:
          type: string
          format: uuid
    Customer:
      allOf:
        - $ref: '#/components/schemas/BaseEntity'
        - type: object
          required: [email]
          properties:
            email:
              type: string
              format: email

Полиморфизм и discriminator

discriminator подсказывает, по какому свойству определить вариант из oneOf / anyOf. mapping связывает значения свойства со схемами; без него значение должно совпадать с именем схемы.

openapi: 3.0.3
info:
  title: Платежи
  version: 1.0.0
paths:
  /payments:
    post:
      summary: Создать платёж
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Payment'
      responses:
        '201':
          description: Платёж создан
components:
  schemas:
    Payment:
      oneOf:
        - $ref: '#/components/schemas/CardPayment'
        - $ref: '#/components/schemas/SbpPayment'
      discriminator:
        propertyName: method
        mapping:
          card: '#/components/schemas/CardPayment'
          sbp: '#/components/schemas/SbpPayment'
    CardPayment:
      type: object
      required: [method, cardToken]
      properties:
        method:
          type: string
        cardToken:
          type: string
    SbpPayment:
      type: object
      required: [method, phone]
      properties:
        method:
          type: string
        phone:
          type: string
          pattern: '^\+7\d{10}$'

XML

Для API, которые отдают XML, объект xml уточняет представление свойства: name (имя элемента), attribute (свойство — атрибут), wrapped (массив в элементе-обёртке), namespace, prefix.

components:
  schemas:
    Book:
      type: object
      xml:
        name: book
      properties:
        id:
          type: integer
          xml:
            attribute: true
        tags:
          type: array
          xml:
            wrapped: true
          items:
            type: string
            xml:
              name: tag