OpenAPI 3.0 vs 3.1: что нового и стоит ли обновляться

Введение

OpenAPI (ранее Swagger) — это стандарт описания REST API, который позволяет создавать понятную и структурированную документацию. В 2021 году вышла версия OpenAPI 3.1, которая принесла важные улучшения и изменения по сравнению с 3.0.

В этой статье мы разберем, что нового в OpenAPI 3.1, какие ключевые изменения были внесены, насколько обратно совместима новая версия, и стоит ли обновляться с 3.0 на 3.1 в 2025 году.

        ✅ Что вы узнаете:
        ✅ Ключевые изменения в OpenAPI 3.1
✅ Сравнение OpenAPI 3.0 и 3.1
✅ Обратная совместимость
✅ Новые возможности JSON Schema
✅ Улучшения в валидации
✅ Стоит ли обновляться
✅ Как мигрировать с 3.0 на 3.1
✅ Поддержка инструментов

    

Обзор версий OpenAPI 📊

OpenAPI прошел долгий путь развития. Давайте кратко рассмотрим историю версий:

Версия	Дата релиза	Ключевые особенности
Swagger 2.0	2014	Первая стабильная версия, широкое распространение
OpenAPI 3.0	2017	Переименование в OpenAPI, улучшенная структура, поддержка callbacks
OpenAPI 3.1	2021	JSON Schema 2020-12, улучшенная валидация, новые типы данных

Ключевые изменения в OpenAPI 3.1 🆕

OpenAPI 3.1 — это эволюционное обновление, которое сохраняет обратную совместимость с 3.0, но добавляет важные улучшения и новые возможности.

1. JSON Schema 2020-12

Самое важное изменение — переход на JSON Schema 2020-12 вместо JSON Schema Draft 4. Это открывает множество новых возможностей для описания данных.

Новые возможности JSON Schema 2020-12:

Unevaluated properties — более гибкая валидация свойств
Unevaluated items — валидация элементов массивов
Dependent schemas — условные схемы
Prefix items — валидация массивов с фиксированными позициями
Content encoding — поддержка различных кодировок

2. Улучшенная поддержка типов данных

# OpenAPI 3.0
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email

# OpenAPI 3.1 - больше возможностей
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          minimum: 1
        name:
          type: string
          minLength: 2
          maxLength: 100
        email:
          type: string
          format: email
          pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
        tags:
          type: array
          items:
            type: string
          minItems: 1
          uniqueItems: true

3. Улучшенная валидация

OpenAPI 3.1 поддерживает более сложные правила валидации из JSON Schema 2020-12:

# Условная валидация
components:
  schemas:
    User:
      type: object
      properties:
        type:
          type: string
          enum: [personal, business]
        email:
          type: string
        company:
          type: string
      if:
        properties:
          type:
            const: business
      then:
        required: [company]
      else:
        required: [email]

4. Поддержка webhooks

OpenAPI 3.1 добавляет нативную поддержку webhooks, что упрощает описание асинхронных операций и событий.

# OpenAPI 3.1 - Webhooks
openapi: 3.1.0
info:
  title: API with Webhooks
  version: 1.0.0

webhooks:
  newOrder:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: Webhook processed successfully

5. Улучшенная поддержка ссылок

OpenAPI 3.1 улучшает работу с $ref и поддерживает больше контекстов для ссылок.

JSON Schema 2020-12: новые возможности 📋

Переход на JSON Schema 2020-12 — это одно из самых значимых изменений в OpenAPI 3.1. Давайте рассмотрим ключевые новые возможности.

Unevaluated Properties и Items

# Пример с unevaluatedProperties
components:
  schemas:
    FlexibleObject:
      type: object
      properties:
        name:
          type: string
      unevaluatedProperties: false  # Запретить дополнительные свойства
      # или
      unevaluatedProperties:
        type: string  # Разрешить только строковые свойства

Prefix Items для массивов

# Массив с фиксированными позициями
components:
  schemas:
    Coordinates:
      type: array
      prefixItems:
        - type: number  # Первый элемент - число (широта)
        - type: number  # Второй элемент - число (долгота)
      items: false  # Запретить дополнительные элементы
      minItems: 2
      maxItems: 2

Dependent Schemas

# Условная валидация на основе других полей
components:
  schemas:
    Payment:
      type: object
      properties:
        method:
          type: string
          enum: [card, bank_transfer]
        cardNumber:
          type: string
        bankAccount:
          type: string
      dependentSchemas:
        card:
          required: [cardNumber]
          properties:
            cardNumber:
              type: string
              pattern: '^[0-9]{16}$'
        bank_transfer:
          required: [bankAccount]
          properties:
            bankAccount:
              type: string

Сравнение OpenAPI 3.0 и 3.1 📊

Критерий	OpenAPI 3.0	OpenAPI 3.1
JSON Schema	Draft 4	2020-12
Webhooks	Нет нативной поддержки	✅ Нативная поддержка
Валидация	Базовая	Расширенная (условная, unevaluated)
Типы данных	Стандартные типы	Расширенные типы и форматы
Обратная совместимость	-	✅ Полная с 3.0
Поддержка инструментов	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
Сложность	Средняя	Выше (больше возможностей)

Примеры различий в синтаксисе

OpenAPI 3.0

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

OpenAPI 3.1

openapi: 3.1.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
webhooks:
  userCreated:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'

Миграция с OpenAPI 3.0 на 3.1 🔄

Миграция с OpenAPI 3.0 на 3.1 относительно проста благодаря обратной совместимости. Большинство спецификаций 3.0 будут работать в 3.1 без изменений.

Шаги миграции

        ✅ Пошаговая миграция:
        Обновите версию — измените openapi: 3.0.0 на openapi: 3.1.0
Проверьте валидацию — используйте валидатор для проверки спецификации
Обновите инструменты — убедитесь, что ваши инструменты поддерживают 3.1
Используйте новые возможности — постепенно внедряйте новые функции JSON Schema
Тестируйте — проверьте, что все работает корректно

    

Пример миграции

# До (OpenAPI 3.0)
openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
        name:
          type: string

# После (OpenAPI 3.1)
openapi: 3.1.0  # Изменено
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
          minimum: 1  # Новые возможности валидации
        name:
          type: string
          minLength: 2
          maxLength: 100
webhooks:  # Новая секция
  userCreated:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'

Автоматическая миграция

Существуют инструменты для автоматической миграции и валидации:

Swagger Editor — онлайн редактор с поддержкой 3.1
Redocly CLI — валидация и линтинг OpenAPI
Spectral — линтер для OpenAPI спецификаций

Стоит ли обновляться? 🤔

Решение об обновлении зависит от ваших конкретных потребностей и ситуации. Давайте разберем, когда стоит обновляться, а когда можно остаться на 3.0.

Обновляйтесь, если:

✅ Рекомендуется обновление:

Вам нужны новые возможности JSON Schema 2020-12
Вы хотите использовать webhooks в спецификации
Нужна более сложная валидация данных
Вы создаете новый API с нуля
Ваши инструменты уже поддерживают 3.1
Вы хотите использовать последние best practices

Можно остаться на 3.0, если:

⚠️ Можно остаться на 3.0:

Ваш API уже работает и не требует новых возможностей
Ваши инструменты еще не поддерживают 3.1
Команда не готова к изменениям
Нет необходимости в сложной валидации
Webhooks не используются

Поддержка инструментов

Инструмент	OpenAPI 3.0	OpenAPI 3.1
Swagger UI	✅ Полная поддержка	✅ Поддерживается
ReDoc	✅ Полная поддержка	✅ Поддерживается
Postman	✅ Полная поддержка	✅ Поддерживается
Redocly	✅ Полная поддержка	✅ Полная поддержка
Code генераторы	✅ Хорошая поддержка	⚠️ Частичная поддержка

💡 Текущая ситуация в 2025:

К 2025 году большинство инструментов уже поддерживают OpenAPI 3.1. Однако некоторые генераторы кода могут еще не полностью поддерживать все новые возможности JSON Schema 2020-12. Рекомендуется проверить поддержку ваших конкретных инструментов перед миграцией.

Практические примеры использования новых возможностей

Пример 1: Улучшенная валидация

# OpenAPI 3.1 - Расширенная валидация
components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: integer
          minimum: 1
        name:
          type: string
          minLength: 3
          maxLength: 100
        price:
          type: number
          minimum: 0
          exclusiveMinimum: true  # Цена должна быть > 0
        tags:
          type: array
          items:
            type: string
          minItems: 1
          uniqueItems: true  # Уникальные теги
        metadata:
          type: object
          unevaluatedProperties: true  # Разрешить любые дополнительные свойства

Пример 2: Webhooks

# OpenAPI 3.1 - Webhooks
openapi: 3.1.0
info:
  title: E-commerce API
  version: 1.0.0

paths:
  /orders:
    post:
      summary: Create order
      responses:
        '201':
          description: Order created

webhooks:
  orderCreated:
    post:
      summary: Order created webhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: Webhook received successfully

  orderStatusChanged:
    post:
      summary: Order status changed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                orderId:
                  type: integer
                status:
                  type: string
                  enum: [pending, processing, shipped, delivered]

Заключение

OpenAPI 3.1 — это значительное улучшение по сравнению с 3.0, которое приносит новые возможности, особенно в области валидации и описания данных. Однако обновление не является обязательным — OpenAPI 3.0 все еще актуален и широко поддерживается.

        💡 Рекомендации:
        Для новых проектов — используйте OpenAPI 3.1
Для существующих проектов — обновляйтесь, если нужны новые возможности
Проверьте инструменты — убедитесь в поддержке 3.1 перед миграцией
Постепенная миграция — можно мигрировать постепенно, используя новые возможности по мере необходимости
Обратная совместимость — спецификации 3.0 работают в большинстве инструментов для 3.1

    

⚠️ Важно помнить:

OpenAPI 3.0 все еще актуален и поддерживается
Не все инструменты полностью поддерживают все возможности 3.1
Миграция должна быть обдуманной и протестированной
Новые возможности JSON Schema могут быть избыточными для простых API

Создайте Mock API за 2 минуты

Хотите протестировать OpenAPI 3.0 или 3.1 спецификации? Создайте Mock API с помощью LightBox API и попробуйте различные возможности описания API без необходимости настраивать сложный backend.

Попробовать бесплатно →

← Вернуться к статьям