# Design-First Versus Code-First — OpenAPI / Swagger

Source: https://www.skillbyai.com/en/openapi/f-approaches

> Compare writing the specification first with generating it from code.

## 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.

```text
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.

**Quiz:** What is a key benefit of design-first API development?

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

*Answer:* Consumers can review the contract and build against mocks before implementation exists. Designing the contract first enables early feedback and parallel frontend and backend work.