Вики врёт, прод молчит: почему пора сделать OpenAPI единственным источником правды о вашем API

[Balek]

Разрешите, я оставлю ссылку на свою вчерашнюю статью: https://habr.com/ru/articles/1043948/

Идея в том, что не надо мучиться с натягиванием OpenAPI на свой проект, а ввести свой язык описания и кодогенераторы, согласованные с вашей архитектурой.

[rlaconic]

Ни одна методология (как и инструменты, приёмы и прочие меры) не существует сама по себе в отрыве от людей, когда её применяют люди. Именно поэтому то, что подходит одной команде, может не сработать у другой — это вопрос квалификации, культуры и дисциплины (факторы связанные, но не тождественные). Но есть вещи, которые подойдут почти всем, — и готовый стандарт с контрактом во главе угла как раз из таких.

Я сознательно не стал затаскивать в статью инструменты более высокого уровня (тот же Microsoft TypeSpec): уместное применение таких абстракций обычно приходит уже после того, как набита рука на базовом контракте. И здесь я бы расставил приоритеты иначе, чем вы. Собственный язык описания и свои кодогенераторы — это вложение, которое нужно спроектировать, выверить и годами поддерживать своими силами. Думаю большему числу выгоднее взять готовый стандарт, уже отлаженный индустрией, хорошо показавший себя на практике, даже при том, что он охватывает меньшую область.
Поэтому совет «не мучиться с OpenAPI, а ввести свой язык» как общий рецепт, на мой взгляд, скорее переворачивает приоритеты: для большинства это не упрощение, а более тяжёлый путь.

Прочитал вашу статью — совпадений во взглядах действительно много, мы про один и тот же принцип. Но «мучиться с натягиванием OpenAPI» — это не про мой опыт. Наоборот: подход облегчал мне даже сольную разработку (даже когда спецификацию приходилось писать самому) — не говоря уже о мультиплатформенных командах. Потому что он даёт лучшее из двух миров: автоматическую генерацию кода из контракта, но без галлюцинаций ИИ. И всё это на основе однажды аккуратно организованного сетевого слоя, который становится привычнее и понятнее по мере использования из проекта в проект.