Есть два подхода, как получить доку по API:
🔵 code first, когда сначала пишем код, потом по нему генерим спецификацию
🟢 contract first, когда сначала пишем спецификацию, затем по ней код.
Когда я пришла лидом, было так: я проектировала апи, бэки пилили реализацию, потом фронт по сваггеру делал свою часть.
Лид фронта был один на несколько команд и делал ревью всех задач фронтов. И часто, увидев уже готовый код фронтенда на ревью, он приходил ко мне и говорил:
«а почему так? а давайте вот так? а давай вот эту строку уже готовую на бэке сделаем»
А код-то уже написан 😭
После пары таких заходов, я поняла: проще заранее обсудить API с фронтом и лидом фронта.
Так мы и перешли к contract first.
Поначалу проектирование делали просто текстом, потом внедрили open api. Сначала делала это сама, потом стала в задачи бэков включать часть с проектированием.
Вообще это умеют и могут системные аналитики. Но пока в командах их не было, мы проектировали API сами.
Удобно и экономит кучу времени:
➕ можно параллелить разработку фронта и бэка, фронту не нужно ждать бэк
➕ всё обсуждается заранее, не нужно переделывать код, если на чем-то не сошлись, а только поправить спеку
➕ тестировщики могут сразу написать тест-кейсы для бэка
Минусы у contract first такие:
➖ надо думать заранее, нельзя «просто начать писать код», как пойдет, там увидеть, что надо бы вот это добавить, а тут можно вот так, и в конце концов контракт выкристаллизуется по итогам работы
➖ если кто-то в процессе вносит изменения и забывает отразить их в спеке, то спека разойдется с реальностью
По итогу, плюсы, на мой взгляд, сильно перевешивают.
А какой подход вам больше нравится?