Code First

Code-first is an API development approach in which the implementation code is treated as the source of truth and the API definition — most often an OpenAPI document — is generated out of that code through annotations, decorators, or reflection. It is the mirror image of design-first, where the contract is authored before a line of implementation is written. For many teams it is the path of least resistance, because it keeps developers in the language and toolchain they already know.

• Code as the source of truth - The API contract is derived from handlers, models, and annotations rather than maintained as a separate artifact.
• Generated definitions - Tools like swagger-core, springdoc, and framework introspection emit an OpenAPI spec from the running code.
• Fast for developers - Little upfront ceremony, which is why it remains, in my experience, the prevailing approach in the wild.
• Drift risk - The definition only stays honest if generation runs continuously; skip it and the docs quietly diverge from behavior.

In real operations, code-first tends to dominate where engineering culture and delivery speed outweigh cross-team contract negotiation, and it can work well when the generated OpenAPI is wired into CI so the definition is regenerated and governed on every build. The tension I keep writing about is that code-first optimizes for the producer while design-first optimizes for every consumer and, increasingly, for agents that need a trustworthy contract before they will call an API. The pragmatic middle ground is to let teams start code-first but treat the generated definition as a first-class, governed artifact rather than an afterthought.