Привет! Меня зовут Александр Панфилов, я фронтенд-разработчик и тимлид с 9-летним опытом. В этой статье я хочу продолжить тему прошлой статьи «Погружение в Swagger: от основ до сложных кейсов в Nest.js». В ней я освещу проблему исправления ошибок в сгенерированном файле, как из одного файла спецификации можно сгенерировать несколько файлов для обработки разных эндпоинтов.
В результате добавления Swagger во фреймворк Nest.js и его качественной настройке на стороне бэкенда я смог сгенерировать файл OpenAPI-спецификации.
Я думал, что автоматическая генерация файла спецификации должна происходить без проблем, но я очень ошибался.
Файл спецификации содержал ошибки. Во спецификации, которую генерировал Nest, ошибок не отображалось. Тогда я решил проверить валидность файла, который он генерирует. На официальном сайте Swagger https://editor.swagger.io/ провалидировал файл и получил список ошибок.
У меня было два пути решения проблемы:
- добиться исправления в самом Nest.js и далее поддерживать эту чистоту;
- исправить ошибки с помощью искусственного интеллекта.
Я сделал это с помощью AI-модели DeepSeek. Далее я просто скопировал файл в репозиторий UI. Это решение мною было принято под влиянием следующих фактов:
- дефицит времени;
- трудоемкий процесс исправления ошибок в Nest.js;
- быстрая валидация и исправление ошибок с помощью ИИ.
Здесь сразу можно задать вопрос — почему этот процесс нельзя было автоматизировать? Для себя я решил, что это излишне трудоемкий процесс, я очень редко меняю API - проще вручную скопировать файл в AI-модель и получить исправленный результат. Если бы это была разработка корпоративного приложения, в котором часто меняется API — да, здесь этот процесс сразу бы попал под автоматизацию. На примере этого случая очень хорошо видно, когда и что нужно автоматизировать, а когда разовую операцию проще выполнить вручную.
Для исправления ошибок я использовал следующие два промпта:
- прикрепил невалидный файл OpenAPI-спецификации и следующий текст: validate open api specification;
- после предложенных исправлений применил следующий промпт — fixed all errors. В результате выполнения все ошибки были исправлены и текст спецификации можно было сохранить в файл.
Идем дальше. На UI-стороне у меня используется Next.js. В него я решил добавить RTK Query для работы с глобальным состоянием и, ключевое, генерацию кода, который будет обрабатывать эндпоинты.
Процесс кодогенерации очень хорошо расписан в документации на официальном сайте https://redux-toolkit.js.org/rtk-query/usage/code-generation или у любого AI-ассистента. Я не буду здесь подробно все описывать и опущу детали. Кому интересно — переходите по ссылке и изучайте. Я хочу здесь сделать упор на то, как это решение можно применить в своем проекте.
Ранее я упоминал, что использую Nest.js. И в его документации, и в документации Next есть очень много готовых решений. Мне они не подходят, потому что в ходе проекта часто превращаются в свалку кода. Исходя из своего опыта, я для себя вывел свою структуру Redux.
Описание структуры:
- api — папка, в которой хранится весь сгенерированный код на базе спецификации Open API;
- config — папка, в которой хранятся два файла конфигурации:
- первый файл содержит базовый конфигурационный файл настройки RTK Query. В документации он называется empty;
- второй файл содержит скрипт автоматического добавления папки api.
- entities — папка с сущностями, которые будут экспортироваться в приложение и предоставлять работу с API;
- schema — папка со всеми схемами, по которым будет генерироваться API;
- остальные файлы — это конфигурационные файлы настройки самого Redux и глобального хранилища.
Такая структура папок позволяет замкнуть всю логику кодогенерации внутри папки Redux, отделить файлы кодогенерации от основной кодовой базы и наружу отдавать только обработанный код. Если возникнет необходимость поменять Redux на что-то иное — это спокойно можно сделать в папке Redux, весь проект не придется кардинально переделывать.
В рамках этой статьи я показал, как можно быстро поправить файл спецификации и почему иногда проще не автоматизировать этот процесс, также мы разобрали, как можно генерировать код взаимодействия с эндпоинтами и каким образом с ним лучше работать.
Всем хорошего кода, поменьше багов. До скорой встречи в следующих статьях!