Design-First Versus Code-First

Where the description comes from

There are two main workflows. Design-first (also called API-first): teams write the OpenAPI description before implementation, review it with consumers, generate mocks so frontend and backend can work in parallel, then implement against it; the document is the contract and tests verify the implementation matches. Code-first: developers write the implementation with annotations or framework metadata, and a library generates the OpenAPI document at build or run time, as with springdoc-openapi for Spring Boot, FastAPI in Python or NestJS in TypeScript. Design-first gives better API design discussions, earlier feedback and stable contracts, but needs discipline to keep implementation in sync. Code-first keeps the description automatically in sync with the code, but tends to leak implementation details into the API and makes design review happen late. Many organisations mix them: design-first for public and cross-team APIs, code-first for internal services, with linting and breaking-change checks in CI either way.

Comparing the two workflows

Both end with a validated, published description; they start in different places.

design-first                                   code-first
---------------------------------------------  ---------------------------------------------
1. write/modify openapi.yaml                   1. write controller code + annotations
2. review in a pull request with consumers     2. build generates openapi.json
3. lint (Spectral/Redocly) + breaking-change    3. lint + breaking-change check on the
   check against the previous version              generated document
4. generate mock server; clients start         4. publish docs; clients integrate after
5. implement; contract tests verify it             implementation exists
6. publish docs and SDKs                       5. contract tests still recommended

strength: early design feedback, parallel work  strength: description always matches code
risk: spec and code drift without tests        risk: late review, implementation leaks into API

Whichever you choose, check it in CI

Both workflows fail the same way: an unreviewed change silently breaks clients. Store the document in Git, lint it and compare it with the previous version on every pull request.

त्वरित जाँच: What is a key benefit of design-first API development?

• The description is generated automatically from code
• No tests are needed
• Consumers can review the contract and build against mocks before implementation exists
• It avoids writing YAML