История одной команды в консоле для преобразования OpenAPI 2 на OpenAPI 3

На работе переходим на контрактное программирование. В рамках задачи нужно было выполнить миграцию с OpenAPI 2 на OpenAPI 3.

Я человек простой: надо — значит надо. Сел, скопировал файл, поменял версию, руками поправил все ошибки. Жалкие 2 дня и всё готово.

Проходит время. Оказывается, не всё сложилось как надо и теперь надо снова взять актуальную спецификацию Swagger 2.0 и перевести в OpenAPI 3.0. С одной стороны, я знаю, что справлюсь за те же 2 дня. С другой тратить их так бездарно во второй раз не хочу. А вдруг будет третий раз? Четвёртый? Жизнь непредсказуема.

Применяю секретный запрещённый навык: ищу решение в интернете.

По итогам изысканий получаю команду

cd "/Users/cex/Downloads/Новая папка" && npx --yes swagger2openapi swagger.yaml -o openapi.yaml -y

Разбор по частям

• cd — сменить текущую директорию
• && — логический «И»: следующая команда выполнится только если cd завершилась успешно
• npx — запуск npm-пакета без глобальной установки
• —yes — автоматически отвечать «yes» на вопросы npx
• swagger2openapi — CLI-утилита для конвертации Swagger 2.0 → OpenAPI 3.x
• swagger.yaml -o openapi.yaml — входной и выходной файлы
• -y — авто-подтверждение для самой утилиты

Итого: команда заходит в папку с swagger.yaml и конвертирует его в openapi.yaml формата OpenAPI 3. Без единого лишнего вопроса.

На выполнение ушло ~5 секунд.
Не всё конвертировалось идеально, ещё ~40 минут потратил на мелкие правки. Но в целом всё работало после конвертации.

2 дня → 41 минута. Неплохой такой прирост.

И тут становится очень хорошо видно цену ручных операций: один раз «потыкаться» 2 дня — это опыт, второй раз — уже расточительство, третий раз — системная проблема.

К чему это всё? Иногда мы знаем путь и идём по нему на автопилоте. А стоит выдохнуть, немного подумать и оказывается, что есть маршрут в разы быстрее. Считаю себя в этой истории победителем: со второго раза пошёл верным путём 🙂