Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 37 ยท Design-first Workflows

Design-First vs Code-First API Development

Compare design-first and code-first OpenAPI workflows, learn the steps of each, when to choose which, and try a runnable mini code-first spec generator and a decision scorecard.

There are two ways to get an OpenAPI document. In a code-first workflow you write the server, add annotations or type hints, and a tool extracts the spec from the running code. In a design-first workflow (also called contract-first or API-first) you write the spec before any code, review it with everyone involved, and then generate stubs, mocks and docs from it.

Neither is always right. This lesson compares them honestly, so you can pick on purpose. The tools mentioned are real, but they cannot run on this site; runnable Python stand-ins show the mechanism of each approach.

Two ways to a spec

Code-first Code leads, spec is extracted
Design-first Spec leads, code follows
1 / 2

The code-first workflow

  1. Write endpoints in your framework.
  2. Annotate them: types, validation rules, docstrings, response models.
  3. A library builds the OpenAPI document from those annotations at build or run time.

Examples: FastAPI (generates /openapi.json automatically), Spring with springdoc-openapi, ASP.NET with Swashbuckle or the built-in OpenAPI support, NestJS with its Swagger module, tsoa for TypeScript, Laravel packages such as Scramble.

Strengths: fast to start, the spec always matches what the code can do, one language and no separate file to maintain.

Weaknesses: the API shape is decided by whoever writes the controller. Consumers see it late. A refactor can change the spec by accident, and generated documents are often thin on descriptions and examples.

A code-first generator in miniature

The stand-in uses decorators to register routes and builds a spec from them, the same trick frameworks use.

Python Stand-in: decorators produce a spec

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice what is missing from the result: descriptions of parameters, examples, error responses. Annotations only capture what the code already knows.

The design-first workflow

  1. Draft the spec: paths, schemas, examples, errors. Tools: Swagger Editor, Stoplight Studio, Apicurio Studio, Redocly, or a plain text editor with a linter.
  2. Review it like code: open a pull request, let front-end, mobile, QA and partner teams comment.
  3. Mock it with Prism so consumers can try the API at once.
  4. Generate server stubs and client SDKs.
  5. Implement and verify with contract tests so the code cannot drift.
  6. Change the API by changing the spec first.
flowchart LR
  A["Draft spec"] --> B["Review<br/>pull request"]
  B --> C["Mock server"]
  C --> D["Consumers try it"]
  D -- "feedback" --> A
  B --> E["Generate stubs<br/>and SDKs"]
  E --> F["Implement"]
  F --> G["Contract tests in CI"]
  G -- "spec change" --> A

The spec stays at the center; code and tests hang off it.

Strengths: early feedback, parallel work (front-end on the mock, backend on the stub), consistent style, better descriptions because the spec is the product.

Weaknesses: more upfront work, a risk of drift if nothing checks the code against the spec, and extra tooling to learn.

Choosing between them

A weighted scorecard is a useful conversation starter. Change the weights to match your project and see which approach comes out ahead.

Python Stand-in: weighted decision scorecard

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Some rules of thumb:

  • Public or partner API, many teams: design-first.
  • Internal service, one team, rapid change: code-first can be enough, if you lint the generated spec.
  • Existing code without a spec: start code-first to get a baseline, then move to design-first for new endpoints.
  • Hybrid: design the spec by hand, generate stubs, then run contract tests so that code-first drift is caught.

Whichever you choose, put the spec in version control, lint it in CI, and fail the build when the running code and the document disagree.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. In a design-first workflow, where does a new field start?

    Changes begin in the spec, which is reviewed and then used to generate or verify code.
  2. 2. What is a main weakness of pure code-first generation?

    Specs extracted from code only contain what the code knows, and consumers see them late.
  3. 3. How does a design-first team let front-end developers start before the backend exists?

    A mock built from the spec answers requests with examples, so both sides can work in parallel.

Summary

  • Code-first extracts the spec from code; design-first writes the spec first and builds from it.
  • Design-first brings early feedback and parallel work; code-first brings speed and automatic sync.
  • Use contract tests and linting to avoid drift in either approach.
  • Public APIs with many consumers usually benefit from design-first.
  • The decorator and scorecard code are stand-ins for the ideas.

Next: API style guide and governance