Skip to content

OpenAPI Schema and Frontend Types

OpenAPI Schema and Frontend Types

Overview

This guide previously covered an MSW (Mock Service Worker)-based workflow — generating TypeScript types from the OpenAPI schema and keeping MSW request handlers in sync with it. That workflow no longer applies. A search of tracker-frontend-svelte/src, tracker-admin-svelte/src, and packages/tracker-shared/src for msw turns up nothing — the current frontend test suite doesn't mock API responses at all; it tests pure utility functions directly (see Testing). There is also no generate-api-types script (or any OpenAPI-to-TypeScript codegen script) in either app's package.json today.

Current reality

  1. Schema generation still exists and is still useful. Run:
./scripts/generate_simplified_openapi.py --output openapi.json

This is the same script used to produce the root openapi.json, which is also mounted read-only into the frontend-svelte-dev and admin-svelte-dev containers (see compose.yml). Copies of it also live at tracker-frontend-svelte/openapi.json and tracker-admin-svelte/openapi.json for reference.

  1. Request/response types are hand-written, not generated. The TypeScript interfaces used by the frontend (Tracker, Brand, ProductionRun, User, etc.) live as plain interface declarations in packages/tracker-shared/src/api/*.ts (trackers.ts, brands.ts, production-runs.ts, auth.ts, clients.ts, locations.ts), written and maintained by hand next to the request functions that use them. When the backend's Pydantic schemas change, these interfaces need to be updated manually to match — there is no build step that regenerates them from openapi.json.

  2. There is no mock API layer in the test suite. Tests don't intercept fetch calls with MSW or anything else; they import and call exported functions directly (see tracker-frontend-svelte/src/lib/utils/*.test.ts for examples). If a function under test needs API data, tests construct plain objects (e.g. via small make*() factory helpers) rather than mocking an HTTP layer.

Practical workflow when the API changes

  1. Update the backend endpoint/schema as needed.
  2. Regenerate openapi.json with ./scripts/generate_simplified_openapi.py --output openapi.json if you need an up-to-date reference of the contract.
  3. Manually update the corresponding hand-written interface(s) and request function(s) in packages/tracker-shared/src/api/.
  4. Update any call sites in tracker-frontend-svelte / tracker-admin-svelte that consume the changed shape.
  5. Add or update a unit test under src/lib/utils/ (app-local) or alongside the shared logic in packages/tracker-shared/src/ if the change affects testable business logic.

Troubleshooting

  • If a frontend type looks stale relative to the backend, check the hand-written interface in packages/tracker-shared/src/api/ — there's no generated file to blame, it just needs a manual edit.
  • If you're looking for a mock handler for a test and can't find one, that's expected — there's no MSW layer; write a plain unit test against the underlying function instead.
  • If the root and per-app openapi.json files disagree, regenerate all three with the same script run to keep them in sync.