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

По своему опыту могу сказать, что оптимальным вариантом будет описание API руками системного аналитика с последующим согласованием названий переменных и ревью спеки с программистом (как в скраме - выделили время, почитали и обсудили спеку и флоу, который она будет покрывать. Таким образом в контекст войдёт разработчик). С точки зрения жизненного цикла спеки СА - более правильно решение потому, что я редко встречал спеку, которая не менялась в начале (чаще всего) и впоследствии. Кроме того, её надо отвалидировать на логику работы апи и оставить где-то исторические записи зачем (и как) оно всё было прикручено, контакты стейкхолдеров и прочие прелести.

В чём описывать - вопрос к потребителям. Если вы описываете API которым будет пользоваться большое количество потребителей, то лучше в сваггер. Но для аналитика изучение OpenAPI 2 или 3 версии займёт достаточно много времени и потребует итерационного улучшения документации (если она 1-2). Если же потребитель один или пара, то лучше обходиться обычными таблицами.

Сейчас в компании налаживаю работу через микросервисы + автодокументацию апи через сваггер. Просто прикрутить сервис в большой компании с разветвлённой структурой не так то просто (нужно ещё развернуть МОКи, сваггер интерфейс пользователя, настроить прод и предпрод...). Не все девопсы и разработчики готовы вписаться в такое. Требуются административные решения, нужно правильно продать решение, попробовать на паре компонентов, приучить к этому котов и продавить девопс, чтобы они смогли помогли нам улучшить нашу жизнь.
Тут возможно разработчик-сеньор скажет, что там делать нефиг, но это если есть опыт и структура простая. Так что сваггер не так-то просто развернуть бывает.

АПИ может сделать и разработчик, который возьмёт на себя часть работ с неопределённостью. Но тут нужен грамотный специалист, а не кодер. Кроме того, есть проблема того, что может остаться документация, которую впоследствии будет невозможно использовать.

Спасибо за ответы!

Мнения хорошие, мнения разные)))

Из опыта: я описываю данные которые должны передаваться, а тимлид уже назначает переменные и коды ошибок

в каком виде описываете?

написала в личку

Минутка пятничного юмора.
Поставил шуточный дескрипшн себе в профиль

PdM>BA. BA! = SA. PdM! = PM. PM=2, PdM=8, SA=5. Чему равен BA?

Кто решит?

-1?

42

PdM и PDM одно и то же?

расшифруйте пожалуйста

я бы сказал да

это product manager

Понял откуда вопрос. Поправлю ща

0?

нет

есть решение логичное