Решил тут присмотреться к OpenAPI 3.1, интересно стало, что там нового и стоит ли она того, чтобы обновлять наши текущие спецификации API. Провел небольшой тест-драйв, могу поделиться наблюдениями.

Плюсы:

• Поддержка JSON Schema Draft 2020-12 – это прям большой шаг вперед для описания данных.
• Улучшенная поддержка различных форматов, стало проще описывать сложные структуры.
• Более строгие правила валидации, что полезно для отладки.

Минусы:

• Миграция со старых версий может быть муторной, особенно если у вас много кода, генерируемого из спецификации.
• Инструменты еще не все успели обновиться, иногда приходится искать обходные пути.

Вывод: OpenAPI 3.1 – это, безусловно, будущее. Если вы только начинаете проектировать API, начинайте сразу с нее. Старые проекты, как всегда, потребуют внимания. Кстати, нашел где-то Крáкен сайт с разбором примеров, если кому интересно.

Крáкен актуальная ссылка