By name: skill-api-sync description: Skill for maintaining parity between Spring Boot (OpenAPI/Swagger) models and React (TypeScript) interfaces. Use when adding endpoints or updating the backend data schema.
API Synchronization Skill
This skill ensures consistent data typing between the backend Edge Service and the frontend application.
Core Workflow
- Update Schema: Edit
backend/src/main/resources/schemas/swagger.jsonto define new models or endpoints. - Generate Backend: Run
mvn clean installin thebackend/directory to regenerate Java interfaces and models. - Synchronize Frontend: Update
frontend/src/types/api.tsto match the generated backend models.
Type Mapping Reference
| OpenAPI / Java | TypeScript |
|---|---|
Integer, Double, Float, Long |
number |
String, UUID |
string |
Boolean |
boolean |
List<T>, Set<T> |
T[] |
Map<String, T> |
Record<string, T> |
OffsetDateTime, LocalDate |
string (ISO format) |
Best Practices
- Enums: Always define enums in
swagger.jsonso they are generated correctly as Java enums and can be mapped to TypeScript string literal types or enums. - Nullable Fields: Explicitly mark required fields in
swagger.json. Frontend types should reflect optionality (fieldName?: type). - Validation: After updating
api.ts, runnpm run buildortscin the frontend to find breaking changes.