Проект OpenAPI Initiative представил новую минорную версию спецификации — OpenAPI Specification v3.2.0, которая приносит ряд важных улучшений, особенно для тех, кто строит сложные API, работает с потоками данных и уделяет внимание безопасности. (OpenAPI Initiative)

Основные изменения

1. Улучшенная работа с тегами (Tags)

  • Появилась новая структура Tag Object, включающая поля summary, parent (для вложенности) и kind (для классификации).

  • Теперь теги можно организовать в иерархии (например, "Products → Books") и задавать разные виды тегов, что упрощает визуализацию и группировку операций.

  • Введён реестр (registry) стандартных значений kind, чтобы сообщество могло делиться общепринятыми классификациями.

2. Расширенные HTTP-методы и дополнительные возможности

  • Спецификация теперь официально поддерживает HTTP-метод query — для безопасного запроса состояния ресурса с возможностью передавать сложные параметры (используя Schema Objects).

  • additionalOperations: возможность определять произвольные HTTP-методы, не только стандартные, с помощью Map, где каждый метод представлен стандартным Operation Object.

  • Введён новый компонент querystring, позволяющий задавать все параметры query как единый Schema Object — это упрощает валидацию и унификацию параметров запроса.

3. Поддержка потоковых (streaming) медиа-типов и форматов

OpenAPI v3.2 добавляет официальную поддержку таких форматов:

  • Server-Sent Events (text/event-stream)

  • JSON Lines (application/jsonl)

  • JSON Sequences (application/json-seq)

  • Multipart Mixed (multipart/mixed)

Кроме того, введён ключ itemSchema, который позволяет описывать, как выглядят «события» в потоке — что важно при работе с реальной передачей данных на протяжении времени.

4. Улучшения в безопасности

  • Добавлена поддержка OAuth 2.0 Device Authorization Flow — полезно для устройств с ограниченным вводом (телевизоры, киоски и др.).

  • Новое свойство oauth2MetadataUrl в объекте OAuth Flow, которое указывает на URL, где можно получить метаданные OAuth 2.0 сервера. Это повышает прозрачность и автоматизацию при обнаружении API.

Что это значит для разработчиков

  • Более гибкая организация документации и визуализации API: новые теги и вложенность позволяют создавать более читаемые интерфейсы, особенно в больших API.

  • Расширенные возможности для API-шаблонов с нетрадиционными HTTP-методами и сложными query-структурами: меньше компромиссов, когда стандартные методы не подходят.

  • Лучшая поддержка потоковых сценариев — критично в областях вроде IoT, чат-ботов, финансовых и real-time приложений.

  • Повышенная безопасность и совместимость с современными OAuth сценариями, а также удобство автоматизации и интеграции со сторонними сервисами.

Что дальше: как перейти на v3.2.0

OpenAPI Initiative подготовила сопутствующие материалы:

  • Спецификация версии v3.2.0 на официальном сайте. (OpenAPI Specification v3.2.0)

  • Подробные release notes (список всех изменений). (Release Notes)

  • Руководство по миграции для тех, кто использует предыдущие версии. (Migration guide)