Skip to content

openapi-sync

In plain terms

Keeps the front-end's data types in sync with the back-end automatically, so the two don't drift apart.

What this skill does

Regenerate frontend TypeScript types from the backend OpenAPI schema to keep types in sync.

Stack flavor: fastapi only.

[!IMPORTANT] Run this after ANY backend schema change (new model, changed field, new route). Skipping this causes type drift between frontend and backend.

⚠️ Trigger Conditions

  • Files: Changes to backend/app/models/*.py or backend/app/schemas/*.py.
  • After running /db-migration or /feature-scaffold.
  • Keywords: "Update types", "Sync types", "Regenerate API types".

1. Export OpenAPI Schema

Ensure the FastAPI backend is running (or use the export command): 

cd backend && python -c "
import json
from app.main import app
print(json.dumps(app.openapi(), indent=2))
" > openapi.json
Or if the backend is running: 
curl http://localhost:8000/openapi.json -o backend/openapi.json

2. Generate Frontend Types

From the openapi.json, regenerate the TypeScript types: 

cd frontend && npx openapi-typescript ../backend/openapi.json -o src/types/api.ts

[!NOTE] The exact command depends on the generator configured in frontend/package.json. Check for a generate:types or openapi script first.

3. Verify

  • [ ] No regressions: Check that existing usages of @/types/api still compile: cd frontend && npm run type-check.
  • [ ] New types present: Confirm new models/schemas appear in frontend/src/types/api.ts.
  • [ ] No manual edits: frontend/src/types/api.ts is a generated file — never manually edit it.

4. Commit

  • [ ] Commit both backend/openapi.json and frontend/src/types/api.ts together so the repo always stays in sync.