Comments 24
Вы только что придумали OpenAPI
Про OpenAPI мы знаем) как я уже писала в статье, сначала этот формат и использовали: описывали контракты в сваггере, затем передавали yaml разработчикам + в конфлюенсе описывали маппинги и сценарий обработки. Но такой вариант команде не особо зашел и мы все перенесли в конфлюенс.
Вы GUI для редактирования OpenAPI не пробовали? Типа stoplight.io
Там, мне кажется, меньше возьни с поддержкой всей документации. Конфлюенс конечно работает, но это же как в Excel делать ML модель.
Нет, не знаете, если передавали YAML разработчикам. У вас на выходе должна получиться подробная документация и, главное, автоматом! А не как вы руками в Confluence. OpenAPI и тьма инструментов вокруг него позволяют это делать без каких-либо проблем.
Вот стоило бы раскрыть во введении к статье про "не особо зашел". Если дело исключительно в этом:
Параллельно описывали сценарии обработки запросов и маппинг параметров API в конфлюенсе.
то в чём именно проявилось неудобство в разработке и использовании частей спецификации в разных местах?
Жаль, до сих пор люди активно не используют Problem Details для ошибок, каждый проект жуткий кастом :(
А зачем вы вообще это делаете? Зачем аналитику вставать между бекенд-разработчиком и фронтенд-разработчиком и пытаться что-то "проектировать" на стыке бека и фронта? Разработчики (если это нормальные компетентные разработчики) могут сделать это самостоятельно и более качественно.
Результат работы системного аналитика - требования к ПО, зачем пытаться залазить еще и в проектирование?
Видимо весь вопрос в "если". Особенно это заметно на больших проектах.
Потребности рынка с вами не согласны. В компентеции системного аналитика в РФ уже как много лет входит большой пласт работ по проектированию решений - и как раз разработка спецификаций API стоит в первых рядах. При этом обязанность по выявлению и анализу требований никуда не уходит.
Согласен что в некоторых компаниях такая практика есть, но не соглашусь что это норма и "потребности рынка".
Собеседовал (или участвовал в собеседовании) порядка 200-300 системных аналитиков, тех кто прямо "проектировал API" было от силы 20%. Возможно выборка смещенная (кандидатов уровня Senior было не так много), но всё же.
Сколько копипасты-то.. Вот потратили вы человеконедели на написание этого всего. Потом каждое более-менее существенное обновление будет требовать ещё человекодни. А разработчик, вместо того, чтобы написать один раз обобщённый код, будет теперь описыват 100500 ручек по каждому ресурсу в отдельности, тратя на это ещё чловекондели. Вот смотрите, описание вашего сервиса в 25 строк без воды:
Причём оно ещё и машиночитаемое. По нему можно генерить админку, схему бд, правила проверки прав и различной фильтрации данных. Надо ли говорить, что прикручивание новых фич при таком описании требует человекоминуты, а не человекодни?
Простите, что это за формат?
Спасибо. Не нужно. Есть всем известный, понятный и всеми поддерживаемый формат Open API, который ко всему прочему генерируется прям из бекенда зачастую, развивается очень давно.
Надо ли говорить, что прикручивание новых фич при таком описании требует человекоминуты, а не человекодни?
Стандартное заблуждение. Давайте приделаем low code, и тогда вообще программистов можно будет уволить и всё описывать нотациями, а там и код сгенерируется и всё-всё-всё. Даже если проект такой примитивный, квадратно-гнездовой, типа тупых крудов, то и тогда -- нафиг это нужно? "Админка" блин. Проще взять IDE для БД и не париться.
Что это за формат, можно поинтересоваться? И каким инструментами потом можно генерить схему бд и ТД? Заранее спасибо
Такое ощущение, Confluence – лишнее требование в этой методике. Тем более в «новой реальности». Вероятно, и другие уважающие себя таск-трекеры умеют в таблицы и шаблоны. Для джуна вроде норм расписано. Для мидла слишком простецкая задача. Синьор тоскливо отметит, что для единообразия много чего следует вынести на самый верх, на уровень всего API или даже выше, большими буквами: все параметры и ответы по-верблюжьи, а поля БД по-змеиному (кстати, в примеры из базы пролез таки snake case); все даты в ISO UTC (в ТЗ не нашёл про часовой пояс котов); единые для всех сущностей названия параметров для сортировки/языка/пагинации/даты создания/даты изменения; обязательная валидация по размерам и форматам. Совсем печально, что аналитик предлагает заниматься валидацией и авторизацией (почему-то после валидации) на уровне роута. И раз у вас FastAPI, его встроенный форматтер ошибок подружелюбнее будет.
Курлы аналитики руками пишут?
Хорошая статья? (а комментарии к ней делают ее только лучше)
Интересно посмотреть на альтернативный формализованный подход к описанию интеграционной документации. Сам сталкивался с тем, что при описании работы сложных сервисов, таких как спотовая биржа на микрофронте, одного лишь Swagger недостаточно разработчикам для понимания тяжеловесной логики, поэтому документация в конфлюенс была спасением)
Вы упомянули про еще один формат документации: "Требования к фронтенду с описаниями экранных форм и вызовами API мы оформляем отдельным артефактом." – может быть и по этому фреймворку сделаете статью?
Никогда не понимал желание аналитика залезть в области, где ему делать нечего. Ваша обязанность - описать пользовательские сценарии, и результаты выполнения этих сценариев. Для этого вообще не нужны ни Swagger в частности, ни OpenAPI в целом. Поскольку тот же Swagger никак не может описать изменения в БД после выполнения сценария. А оно как бы надо. Ну и 2 ОЧЕНЬ больших косяка (это как пример, на самом деле их даже не десяток) у вас лично, при попытке влезть в чужую предметную область:
Ограничение на catId стоит только not null. Подскажите, он у вас действительно может быть отрицательным? Зачем? Это была неудачная попытка влезть в область системного архитектора.
Поля с датами у вас date_created и date_updated. Жестко прописаны. Например в Laravel эти поля по умолчанию называются created_at и updated_at. Таким образом вы создаете абсолютно ненужную работу программисту, залезая в его область.
Ну и как добрый совет, почитайте уже наконец про BDD (Behavior-driven development). Вот это уже сильно ближе к работе аналитика, нежели перенос описашек из Сваггера в Конфлюенс.
Как мы описываем требования к REST API для бэкенда в Confluence