OpenAPI или месяцы программирования берегут часы проектирования

[levgem]

За 4 месяца мы почти полностью внедрили в большинстве продуктов флюссоника работу с OpenAPI и с подходом API first.

Для тех, кто смутно понимает о чём речь, сразу добавлю несколько атрибутов, которые должны пояснить что именно происходит.

Речь идет о том, что у нас в отдельном репозитории лежат текстовые файлы, которые могут редактировать и читать

Comments

[belezbar]

Такой подход хорошо описан в главе "Сила простого текста" в "Программист прагматик". Отсюда же, наверное, растут ноги у философии "инфраструктура как код", где мы редактируем только декларативную часть, а дальше "оно само" всё разворачивается, как ему указано.

[roastedcode]

Еще это:

4. Готовые валидаторы ввода, более или менее одинаково работающие для разных языков.
5. Способ генерировать вменяемую документацию быстро и с небольшими усилиями.

Сам пользуюсь Swagger/OpenAPI уже лет пять.

[levgem]

Да, валидаторы - ок, правда для эрланга хрен чего нашлось, пилили руками.
Больше проблем оказалось с валидатором вывода, несколько месяцев систематизировали всё то, что выдавалось наружу нашим софтом =)

Документация - всё верно. Есть что улучшать, но https://flussonic.com/doc/api/reference/

[jakobz]

Т.е. у тебя не-программисты прям JSON этот пишут, в рамках там оформления задач или документации?

В принципе, идея вынести все схемы в отдельную репу - очень годная и правильная. У меня тоже такая репа есть, но она больше из утилитарных целей сделана - ну там генерацию кода централизовать, например. И вот эта твоя success story вдохновляет попробовать эту идею развить. Ибо задолбало вот это всё "ой мы релизнули, забыли что вы API юзаете", или "давайте организуем процесс change management-а через бумажки на confluence".

Короче я бы даже поподробнее послушал. Обычно такие инициативы губят на уровне разработки или менеджмента. Ну типа это надо яйцы чтобы такое провести - потому что против будут и разрабы ("Ой, мне тут одно nullable поле добавить, а такой гемор") и менеджмент ("мне разработчик сказал что из-за этого он потратит день вместо часа"). Не было подобных проблем?

[levgem]

Да, у меня прям не-программисты пишут этот yml, он валидируется и если ок, то можно мержить в мастер.

Если кому-то хочется добавить какие-то ограничения на схемы, обусловленные особенностями кода, который её будет имплементить, он должен добавить код в линтер, чтобы формализовать свои требования.

Отдельный репо - это must have, чтобы убрать всё лишнее. Менеджер делает ветку, она зеленеет, под ней подписываются девелоперы, её мержат. Дальше тесты или тестировщик выявляют что продукт не имплементит новое апи и это исправляется.

Против были и разрабы, и тимлид (он не понял чего я вообще сделал, а потом мы расстались), но потом когда стало ясно, что мы реально экономим по месяцу работы повертев в руках три ямля, стало легче.

Т.е. внедрял я сверху и довольно насильно.

[evtuhovich]

Я посмотрел - клевый подход. Полистал ваш api и понял, что он единственно верный, оно реально развесистое :-)

Единственное, я скачал swagger.json, а он под 10к строк, я ведь правильно понимаю, что вы из пачки yaml-файлов его собираете?

[levgem]

Да, конечно из пачки ямлей, да ещё и предпроцессинг свой делаем.

У меня одни и теже файлы физически в разные проекты включаются. Это нужно чтобы не было расхождения и мучительного рефакторинга по сведению всего воедино.

Если хочешь - давай я тебе доступ в наш репозиторий со схемами дам?

[evtuhovich]

Спасибо, давай, я посмотрю, как это выглядит. evtuhovich@gmail.com на всякий случай