Меня зовут Максим и я разработчик фронтенда панели управления услугами компании «Миран». В данном цикле статей я расскажу вам, как эволюционирует система и что нового стоит ждать в ближайшем будущем. Добро пожаловать под кат.  Старая панель, или panel_v1, базируется на Django со стороны бэкэнда + TastyPie в роли API + AngularJS во фронтенде. Выбор основывался на хорошей документации и возможности обойтись небольшим напильником для доведения фреймворка до необходимого нам состояния. Связка Django и Tastypie предоставляли все необходимые инструменты для наших запросов, а AngularJS был достаточно удобен для отображения данных. Как известно, требования постоянно расширяются и когда они стали превышать возможности панели, было принято решение о полной смене архитектуры и эволюции стека технологий. Была проведена «инвентаризация» кода и после этого работа над ним была заморожена и ограничена только минимальными правками. А мы получили возможность выбрать какой будет новая панель управления.  Главным вопросом стал выбор архитектуры. Учитывая существующий опыт из panel_v1 и возможности tastypie мы решили развить идею и разбить всю панель на части, связать через api и управлять всеми частями индивидуально. Поэтому выбором стали микросервисы. Ведь крайне удобно иметь небольшие модули, которые выполняют строго свою задачу и при для изменения их работы? изменении в их работе достаточно обновить интерфейсы для остальных микросервисов. Решение принято, супер. Для бэкэнда будет достаточно легковесного, но мощного Flask, фронтенд переедет на новый Angular2. Вроде всё выглядит хорошо, но как же им общаться?
Тут необходим API, который будет достаточно гибким и подходить для бэкэнда и фронтенда с минимальными изменениями. Тем более его необходимо будет открыть клиентам, а значит без подробной документации с примерами использования никуда/не обойтись. Вот тут-то мы и призадумались.  Решением нашей проблемы стала спецификация OpenAPI в реализации Swagger. Вот краткий список возможностей Swagger: Но не бывает всё гладко. Ниже приведен краткий список подводных камней, с которым мы столкнулись. По умолчанию файл спецификации можно разбивать и хранить, например, definitions (объект, содержащий описание данных, циркулирующих в операциях) отдельно и обращаться к нему через ссылку. Но такой вариант не заработал из-за connexion. Текущая версия пакета не предусматривает этой возможности (искренне надеюсь, что в следующий версиях её добавят). А пока пришлось выкручиваться следующим образом: все объекты сущностей (definitions, paths, responses, etc.) выделены в файлы и собираются с помощью grunt. В итоге получился набор задач, которые можно легко добавлять и менять. На мой взгляд такой вариант лучше, чем поиск нужной строки среди ~2500 строк итогового файла.
Вот выдержка из задачи для клиентской части: Добавление отступов “Склеивание” промежуточных и итоговых файлов Данная проблема обнаружилась в тот момент, когда я исследовал как swagger-codegen может выполнять сборку. Есть два варианта: предоставить файл спецификации или скачать его. И тут мы решили собирать из файла, так как сервис API может отказать и это повлияет на работу фронтенда. Поэтому выбрали готовый файл. Репозиторий был подключен как git submodule, что обеспечило постоянную актуальность. Алгоритм получился следующий: Но всплывает подробность, что на вход swagger-codegen принимает JSON. А у нас YAML. И тут мы поняли, что угадали с Grunt. Подключением плагина YAML to JSON брюки превраща… Тьфу. YAML превращается в JSON. А мы получаем необходимый файл спецификации. Тут сказались настройки swagger-codegen при именовании методов и переменных в typescript. Например, имя свойства “total_count”. Без настроек компиляции typescript имя переменной становилось totalCount. При попытке решения данной проблемы обнаружилось, что можно вместе с файлом конфигурации передать файл дополнительных настроек в формате JSON. И эта строка: оставляет имена без перемен. В следующем выпуске я расскажу, с чего начался тернистый путь разработки фронтенда и как удалось оптимизировать загрузку панели. Спасибо за внимание!) Frontend-разработчик