Для ведения версионности OpenAPI Specification (OAS) используется Semantic Versioning 2.0.0 (semver) далее по тексту semver specification.
Глоссарий
Мажорная (major) - основная версия. Первая цифра.
Минорная (minor) - дополнительная (младшая) версия. Вторая цифра.
Патч (patch) - Версия исправления. Третья цифра.
Мажорные и минорные части semver (например, 3.0) ДОЛЖНЫ назначаться набору функций. А патч версии затрагивают ошибки в документе и не относятся к набору функций. Инструмент, который поддерживает OAS 3.0 ДОЛЖЕН быть совместим со всеми версиями OAS 3.0.*. Инструментарий НЕ ДОЛЖЕН учитывать версию исправления, например, не делая различий между 3.0.0 и 3.0.1
Каждая новая минорная версия спецификации OpenAPI ДОЛЖНА позволять обновлять любой документ OpenAPI, который действителен для любой предыдущей минорной версии Specification в рамках той же основной версии, до новой версии Specification с эквивалентной семантикой. Такое обновление ДОЛЖНО требовать только изменения свойства openapi на новую младшую версию.
Например, действительный документ OpenAPI 3.0.2 после изменения его свойства openapi на 3.1.0 ДОЛЖЕН быть действительным документом OpenAPI 3.1.0, семантически эквивалентным исходному документу OpenAPI 3.0.2. Для обеспечения такой обратной совместимости должны быть написаны новые минорные версии спецификации Open API.
Документ Open API, совместимый с OAS 3.*.*, содержит обязательное поле openapi, которое указывает семантическую версию OAS, которую он использует.
{
"openapi": "3.0.3"
}
Документы OAS 2.0 содержат поле версии верхнего уровня с именем swagger и значением "2.0".
{
"swagger": "2.0"
}