Миграция рабочей документации на OpenAPI для HeadHunter
Специалисты SimbirSoft приняли участие в масштабном проекте HeadHunter, работа над ним заняла около 3 лет. Задача состояла в том, чтобы перевести рабочую документацию внутри корпоративного программного продукта из формата Markdown на актуальный интерактивный инструмент OpenAPI, добавить новый функционал в автотесты и оптимизировать унаследованный код.
Новые функции и возможности перехода позволили компании создать логичную пользовательскую среду для разных рабочих целей, а разработчикам HeadHunter — иметь под рукой интерактивную инструкцию для быстрой выгрузки данных, когда необходимо провести интеграцию с другими сервисами или для автоматизации. OpenAPI также помогает отлавливать факты обратной несовместимости, синхронизировать русские и английские документы и по ним настраивать разные виды валидации входящих и исходящих объектов.
Задача
Перевести рабочую документацию внутри корпоративного программного продукта из формата Markdown на актуальный интерактивный инструмент OpenAPI, добавить новый функционал в автотесты и оптимизировать унаследованный код.
Как было раньше: до интерактивной инструкции гайд с полезными вводными был представлен в обычном текстовом виде. Для автоматизации процессов такой формат хранения данных не подходил.
Решение
Новый инструмент — функциональней, чем Markdown: он структурирует документацию и предлагает множество опций для работы с ней. OpenAPI позволил проверять актуальность данных, проводить фактчек и генерировать DTO для автотестов. Это сократило время на разработку для интеграторов, а также упростило валидацию самой документации.
Пример автоматизации с помощью OpenAPI такой: основываясь на внутренних данных, система проводит автоматическое генерирование классов для тестов и валидации ответов на запросы. Все превращается в четкую структуру, с кликабельными элементами и деревом тредов.
Результат
В проекте специалисты SimbirSoft провели контроль, проверку и исправление рабочей документации, сгенерировали новые классы по ней, заменили самописные классы на автосгенерированные, адаптировали старые методы для использования новых классов, обеспечили покрытие автотестов валидацией, сделали код-ревью.
В целом, благодаря переходу, получилось добиться:
- генерации DTO по документации;
- возможности проверять документацию на соответствие действительности;
- стандартизации написания документации и вытекающих из этого преимуществ.
Сейчас у Headhunter есть законченный проект с автотестами — сделан глобальный рефакторинг, документация переведена в OpenAPI. Открытая часть проекта доступна по ссылке.
Зачем разработчику нужна инструкция
Для работы с приложением, без входа на сайт: профильные специалисты часто прибегают к помощи API для поиска и обновления информации, без необходимости ручного вмешательства. Иными словами, не всем удобно получать ответы на свои запросы, заходя на конкретный сайт.
Для быстрой выгрузки данных и автоматизации процессов. По сути, инструкция к API помогает получить быстрый доступ к данным и оперативно найти информацию, фильтруя ее. Разработчики могут быстро выгрузить данные в текстовом виде, отфильтровать их и получить выборку по конкретному запросу. Подход удобен экспертам, которые занимаются развитием внутренних систем и используют API для интеграции новых сервисов и продуктов.
Для улучшения качества продукта. Вся проверка рабочей системы идет через спецификацию. Система сверяет данные с инструкцией, и если все работает корректно, автотесты не покажут никаких ошибок: приложение будет работать правильно.
