Как спроектировать API — contract-first vs code-first?

Contract-first: сначала пишешь OpenAPI спецификацию, потом генерируешь server stubs и client SDKs. Преимущества: API согласуется с командой до кода, клиент может работать с mock сразу, строгая типизация. Code-first: пишешь код, потом генерируешь спецификацию аннотациями (springdoc-openapi). Быстрее стартовать, но API может получиться неудобным. Для командной/публичной разработки contract-first лучше — API как документ для обсуждения.