Skip to content

OpenAPI-MSW Integration Guide

OpenAPI-MSW Integration Guide

Overview

This guide covers the current workflow for keeping frontend API mocks aligned with the OpenAPI schema:

  1. generate the latest OpenAPI schema
  2. regenerate TypeScript API types
  3. update MSW handlers and in-memory test data
  4. run the frontend test suite

The goal is to keep mock responses type-safe and synchronized with the API contract.

If you only need schema generation, run ./scripts/generate_simplified_openapi.py --output openapi.json.

Workflow

1. Generate the schema

./scripts/generate_simplified_openapi.py --output openapi.json

2. Regenerate frontend types

cd tracker-admin
npm run generate-api-types

3. Update MSW mocks

Update the generated types, handler logic, and any fixture data that depends on the changed API surface.

Typical changes include:

  • adding handlers for new endpoints
  • adjusting pagination or filter behavior
  • updating response shapes after schema changes
  • keeping error cases realistic

4. Run tests

cd tracker-admin
npm run test:coverage

Use the same three-part split when the frontend has MSW-backed API tests:

  • generated types under src/test/mocks/types
  • in-memory data logic under src/test/mocks/data
  • request handlers under src/test/mocks/handlers

That keeps the test layer easy to update when the API changes.

Practical Notes

  • Regenerate types whenever the OpenAPI schema changes.
  • Prefer real response shapes over over-mocked shortcuts.
  • Keep tests deterministic by resetting in-memory mock state between tests.
  • Review generated type diffs during code review, especially after API changes.

Troubleshooting

  • If types look stale, rerun npm run generate-api-types.
  • If a handler does not match, check the URL, HTTP method, and trailing slash.
  • If tests fail after an API change, update the generated types before debugging the mocks.