Проект 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)
Источник: habr.com