Есть несколько аспектов, которые стоит держать в голове принимая решение - стоит ли его использовать.
Спорная мета
Много лишнего барахла в метаинформации, которое нужно на стадии разработки, но мешает на стадии проектирования.
Можно впасть в аналитический паралич самому и вместе с тимлидом. Если выпутался сам, то тимлид вполне может уйти ковырять в носу на неопределенное количество времени. Или что бы придумать красиво самому или что бы подкинуть контр аргументы тебе, как к аналитику, что бы ты сам вскрывал себе скальп.
Альтернатива 1
Всегда писать абракадабру и не обращать внимание на нытье тимлида.
Альтернатива 2
Откупиться от этой проблемы, мигрировав в конфлю или asciidoc
* * *
Строгая типизация данных
Под этим подразумевается, что все используемые объекты должны быть описаны для возможности расширения и переиспользования.
На скрине пример референса на отдельно описанный тип. 
Альтернатива 1
Не делать объекты вообще, везде копипаста. Но тимлид может тебя выгнать
Альтернатива 2
Таки делать DTO. Но в зависимости от метода, назначение одного и того же атрибутов 100% будет разное. Это значит, что описание объекта будет генерализировано и важные детали будут вычеркнуты
Альтернатива 3
Делать по объекту на метод. Это мало чем отличается от большой копипасты по трудозатратам, но зато можно будет делать красивые дескрипшины (description). Даже с сыллками на требования или проверки. 
Альтернатива 4
Так как копипасты все равно не избежать, то ее можно просто вести в конфле.
Благодаря этому будет:
- тесная связность требований, системной аналитики, архитектуры, фактической реализации, этапности доработок. Банально жира историями можно маркировать новые атрибуты
- не надо умирать над порванной табуляцией ямла, копирование таблиц в конфле работает прекрасно. Как и части таблицы.
Связность теряется, если использовать сваггер в гите, git lens в VS Code, а требования в конфле.
* * *
Проектирование вложенных объектов
Проблема прямо вытекающая из предыдущего пункта
Альтернатива 1
Строгая типизация данных с объектом под метод решает эту проблему. Долго дорого отлично.
Альтернатива 2
Копипаста в ямле, тоже вполне себе альтернатива. Дешево в начале, дорого в сопровождении.
Альтернатива 3
Таблички и примеры в конфле. В таблицах очень плохо передается табулирование и обозначается начало и конец вложенного объекта, но это вполне решается нотацией, похожей на обычную линуксовую команду tree для обзора каталогов.
Альтернатива 4
По табличке на каждый объект в конфле. Тоже ход, и даже можно объектам давать имена, и навешивать хидеры что бы были быстрые ссылки из TOC на публикации.
* * *
Обозначение планируемых доработок
Банально можно обозначить комментариями (не дескрипшином) 
Проблема будет только с тем, что бы определить в какую ветку гита заливать.
Для этого нужны особые церемонии с тим лидом.
Альтернативна 1
Лить все в девелоп ветку. Но тимлид может устать отсматривать незначимые мерж реквесты.
Альтернатива 2
Просто в конфле. Или инлайн комментарием или русским в описании атрибута.
* * *
Обозначение спорных моментов
Проведение внутреннего ревью вполне может проходить через мерж реквесты.
Внешнее ревью или вопросы при интеграции с легаси-сервисом - есть альтернативы
Альтернатива 1
Человекочитаемое письмо.
Менеджеры их понимают и у них даже может быть время написать ответ.
Вместо менеджера можно подставить тестировщика, сап-консультанта, аналитика мидла.
Альтернатива 2
Обозначать комментариями в ямле. Но вполне могут формироваться специальные задачи "ответить на письмо со страшным аттачем", которые могут висеть днями.
Альтернатива 3
Просто задать вопросы инлайн комментарием в конфлюенсе. Можно даже к конкретному слову.
* * *
Проектирование проверок
Все эти ФЛК, специальные проверки по регуляркам и по состоянию в БД предполагают определенный подход:
1. Определить что проверить
2. Придумать текстовку
3. Придумать или подобрать код ошибки из диапазона
Паттерн использования сваггера диаметрально противоположен: ты сначала используешь код ошибки и потом может быть распишешь на какие проверки этот код выбрасывается. Это удобно при разработке по ТЗ, но не удобно для проектирования.
Альтернатива 1
Всем заявить, что ФЛК будет только в 400 ошибках
Все остальное только в 500. Или как то по другому. В общем снова проводить церемонии с тимлидом. 
Альтернатива 2
Не проводить церемонии с тимлидом до того как финализирован список проверок. А таки идти по обычному воркфлоу используя конфлю: корнеркейсы -> тексты -> предполагаемые коды
* * *
Очень высокоуровневый черновик
Проблема явно вытекающая из предыдущего пункта: человеки сначала придумывают пример, который подгоняют под корнер-кейсы, а потом его специфицируют.
Конфля это поддерживает: можешь сделать страницу просто с примерами запроса и ответа.
Сваггер предполагает, что ты сначала умрешь над описанием всех объектов, а потом пример сгенерится тебе сам.
К сожалению, в гибкой методологии разработки это не вариант: требования могут дополниться новым ограничением, концепция может быть резко пересмотрена тим лидом или архитектором. И по нескольку раз все переделывать - себе дороже.
P.S. Похожие мысли подтолкнули одного одиозного разработчика сделать формат Tree, и начать его
проталкивать в массы. Но законы кровавого энтерпрайза гласят: все что после выхода из беты не прошло проверку временем в 5 лет в проде в опенсорсе - не стоит даже рассматривать. Ни 5 лет ни опенсорса пока нет.
Проектирование асинхрона
Вообще сваггер как бы используется для проектирования синхронного взаимодействия по http. И разрабы могут из него нагенерить классов DTO и еррор хэндлеры на генерить. А вот для очередей все на так радужно.
Альтернатива 1
Использовать как есть, не используя коды ошибок.
Или если брокер сообщений используется не для нотифицирования а для взаимодействия "точка точка", то использовать какой-нибдуь любимый код ошибки, что бы загнать в него все проверки со всеми референсами на требования.
Отдельный вопрос: как быть, если консьюмеров много.
Да, можно сделать.. ТЗ на то как обрабатывать поля и приложить ямл. Или приложить ссылку на конфлю. Или СКОПИРОВАТЬ себе текстовое описание контракта, что бы злые смежники его не удалили, перенести, не изменили с потерей старой версии.
Альтернатива 2
Собственно сделать текстовое описание в конфле, что бы его можно было скопировать между пространствами. Ну или в asciidoc сложить, он потрясающе поддерживает таблицы, ссылки в ячейках, вообще всевозможное издевательства с ячейкой.
Субъективные выводы
Сложно предугадать закидоны каждого нового тимлида. Но кое-что остается неизменным:
1. Всем нужно быстро и с минимальными переделками, в том числе в аналитике. Примеры вперед, если успеем - доопишем.
2. Тим лид может хотеть многого, но если манагеры, тестировщики и другие сочувствующие будут не в состоянии использовать и актуализировать артефакты - проект будет скрипеть.
3. Сваггер это безусловно красиво. И даже полезно знать, что из сваггера можно генерить классы и наоборот прикладной код может генерить свагер экзекутор. Но связность аналитических артефактов важнее чем красивая обертка. Не дером Enterprise Architect содержит вообще все типы артефактов: от требований до спецификации классов и есть полная трассировка.
4. Yaml безусловно нагляден, но он все равно чудовищен и по этому постоянно расширяется. Русский язык относительно статичен, и аналитику нужно им владеть по дефолту, в отличие от ямля.
В сумме факторов, confluence выигрывает у swagger.yaml и asciidoc на методы в репозитарии
Комментариев нет :
Отправить комментарий