Part 3: OpenAPI spec from the frontend

The frontend in frontend/ already knows exactly which backend calls it makes: they all live in frontend/src/services/api.ts. Before we write a backend, we turn that knowledge into the API spec, an OpenAPI file that the frontend and backend agree on. Spec-first means the backend has a precise target and the frontend never has to guess what an endpoint returns.

Here we hand work to the coding assistant instead of Lovable for the first time. Start it in the project root.

I run Codex:

codex

Any assistant works the same way, since each prompt is plain English. From here on, "the assistant" means whichever tool you started.

Generate the spec

Point the assistant at the services layer and ask for a spec at the repo root. We treat the frontend as the source of truth here: whatever it calls is what the backend must provide.

Use this prompt:

Read the frontend's API client in frontend/src/services (api.ts and types.ts).
Write an openapi.yaml at the repo root that specifies the backend this frontend
expects: every endpoint, method, path, request body, response body, and which
endpoints need authentication. Use the TypeScript types as the schema source.

The assistant reads the client and writes openapi.yaml, covering the endpoints the frontend already calls.

The endpoints look like this:

POST /auth/signup     create an account, return a token       (201)
POST /auth/login      log in, return a token
GET  /auth/me         the current user                        (auth)
POST /auth/logout     log out                                 (auth)
GET  /leaderboard     top scores, filterable by mode + limit
POST /leaderboard     submit a score                          (auth, 201)
GET  /games/active    active games to spectate

The two game modes show up as an enum, walls and pass-through, exactly as the frontend uses them. Endpoints that change data on behalf of a user - submit a score, read your own profile - are marked as needing a bearer token.

The spec earns its own step

The spec is small, but it does real work. It's the single place where the agreed API is written down. The next step doesn't have to reverse-engineer the frontend a second time, since we hand the assistant the spec and it builds to it. It also documents the API for anyone reading the repo. FastAPI will later serve its own live version at /api/docs, which we can diff against this one to confirm the backend matches.

Open the generated openapi.yaml to read every schema in full. With the API spec written down, we build the backend that fulfils it in Part 4: FastAPI backend from the spec.