Как автоматически распилить монолитный open api файл на 21 000 строк в читаемый вид ?
Есть такая штука - fist api driven подход .
Это когда вы сначала пишете yml файлик или yml файлики с указанием вашего rest api ( урлы эндпоинтов, структура респонса,структура реквеста, коды ошибок и тд).
А потом либо используете в confluence как read-only спеку или генерите код эндпоинтов при копиляции проекта.
Выглядит это примерно так :
Когда размер конфигурационного файла достигает 21 000 строк - внесение изменений в него начинает быть мучительным.
Перебить руками это в ликвибейзоподобный вид можно - но долго и сложно.
В итоге к нам на помощь приходит супер тул - https://redocly.com/ .
Итак погнали разбираться - сначала поставим его на свою тачку.
Я ставил его на мак следующей командой :
Дальше чтобы показать как разбивать - сплитить файл - на мастер с чайлд файлами я использую велком теплейт отсюда https://editor.swagger.io/.
Но с единственным НО - этот тул работает только со спекой в формате open api 3.0.0 .
С swager 2.0.0 к сожалению не пашет - поэтому предварительно надо сконвертить его к формату openapi 3.0.0 если у вас был в формате свагера . Это спокойно делается в онлайн редакторе https://editor.swagger.io/
Итак после того как мы сконвертили - идем в интеледжи и создаем пустой демо проект.
Вставляем туда наш файлик с open api 3.0.0 контентом.
699 строк и это только то что поместилось в экран.
Итак начинаем распил . Сначала заходим в консоль в пакет где находится openapi.yml.
Дока команды : https://redocly.com/docs/cli/commands/split/#split
redocly split - разбить файл на структуру
openapi.yml - путь до файла который разбить
--outDir=openapi_decomposed - директория куда будет положена структура с мастер файлом и чайлд файлами
В папке schemas - лежат файлы каждый из которых представляет структуру одного из реквестов или респонсов .
В папке paths - лежат конкретные файлы описывающие начинку каждого уникального урла .На один файл может приходится несколько методов - GET,PUT,POST - которые прикреплены именно у этому уникальному урлу.
Ну и наконец мастер файл с ссылками на чайлдов. И явными урлами эндпоинтов.
Красное подчеркивание из за того, что тул при генерации в случае с урлами содержащими path variable криво определяет filename .
Но это легко лечится через refactor rename прямо в этой строчке.
Итог : мы повысили читабельность наших конфиг файлов.
Код из статьи : https://github.com/redkatok/redocly_demo
P.S. Также этот тул может собирать несколько файлов open api в один. Советую почитать доку этого инструмента.