Вышла новая версия спецификации OpenAPI 3.2.0 — это важное обновление стандарта описания HTTP-API, которое делает его более точным и гибким, но при этом не ломает существующие спецификации. Всё, что было валидным в OpenAPI 3.1, продолжает работать, так что переход может быть постепенным и безопасным.

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

1. Чёткие правила для путей
Теперь синтаксис шаблонов в URL описан формально. Раньше разные инструменты могли по-разному интерпретировать параметры в {}, что иногда вызывало конфликты. В 3.2 этот момент стандартизирован, что делает спецификации более предсказуемыми и уменьшает количество ошибок при генерации кода и валидации.

2. Поддержка потоковых данных
Появилась возможность явно описывать API, которые возвращают данные в виде потока — например, text/event-stream (SSE) или application/jsonl. Для этого введено новое поле itemSchema, с помощью которого можно указать, как выглядят отдельные элементы в потоке. Это особенно актуально для сервисов, работающих в режиме реального времени.

3. Нестандартные HTTP-методы
До сих пор OpenAPI поддерживал только классические методы (GET, POST, PUT и т.д.). Теперь можно официально описывать и редкие методы вроде LINK или UNLINK, без необходимости использовать хаки и расширения.

4. Улучшенная работа с тегами
Теги стали более гибкими. Теперь можно строить иерархии и добавлять дополнительные атрибуты вроде summary или parent. Это помогает лучше организовывать документацию и делает её более удобной для навигации.

и многое другое.

Ссылки:

Release Notes
Спецификация

Плагин к IDE для редактирования 3.0/3.1