Так да. Пишем спеку => генерим код. Остальные подходы порочны

Если архитектор это член внешнего экспертного центра (не член команды), он может легко на пальцах показать разработчикам, какие инструменты есть (spec first, наличие дизайна, компонентные диаграммы и пр.), чтобы эти проблемы закрыть. И если разработка не загнана, она начнёт эти инструменты сама использовать.

Ну а если член команды, то использовать эти инструменты внутри команды это просто его работа

Любой grpc ;)

И этим он прекрасен: не получится жить без спеки

Можно и генерить спеку. Главное - думать об удобстве API. API-First - это скорее образ мысли, чем конкретный подход.

Главное, чтобы генерация из этой спеки приводила к тому же результату :)

Конечно. Разработчики со всем согласятся и сделают всё по своему.

Именно это я и хотел сказать)

Я про сваггер. Так-то и IDL был

Документация нужна, чтобы кто-то со стороны мог быстро погрузиться в дизайн решения или сделать аудит.

У меня API first обычно выражается в том, чтобы быстро модельку и контроллеры набросает разработчик и сгенерит рыбу сваггера

А дальше уже сваггер допиливается до удобоваримого вида

И по нему делается сервис

Swagger (OpenAPI) codegen неплохо справляется с уровнем интерфейса, далее его шаблоны кодогенерации можно править и добиваться нужного вида кода интерфейса. Этот код должен собираться автоматически в момент сборки и не быть в репозитории (чтобы его нельзя было подправить напильником). Если далее код реализации не будет совпадать с интерфейсом — оно просто не скомпилируется.

Однако, здесь ничего нет про реализацию и бизнес-ограничения. Только формат.

Это один из подходов.

Проблема в том, что всю спеку openapi умеют примерно никто

Повторюсь, мне известны проекты, в которых аналитики пишут дефинишены Swagger, и по ним генерируется код. Дефинишены версионируются, разумеется

Есть такие люди, но мало

Тот же OneOf/AllOf, например.