| name | openapi-sync |
| description | Enforces OpenAPI spec discipline when working on REST API endpoints in this project. Triggers whenever adding, modifying, or removing HTTP routes, request/response types, or API handlers in the Rust web-ui crate (`crates/web-ui`). Reminds the agent to (1) update the committed `openapi.json` spec, (2) run `make dump-openapi` to re-export the spec from the running server, and (3) run `make generate-flutter-client` to regenerate the Dart/dio client in `app/packages/assistant_api/`. Also applies when changing route parameters, status codes, or authentication on existing endpoints. |
OpenAPI Sync Discipline
Any change to the REST API must keep openapi.json and the generated Flutter client in sync. The Flutter app's app/packages/assistant_api/ package is generated code — never edit it manually.
Mandatory Steps After Any API Change
-
Make the server compile and run so the spec can be exported.
-
Re-export the OpenAPI spec:
make dump-openapi
Calls the running server to produce a fresh openapi.json at the repo root.
-
Regenerate the Flutter Dart/dio client:
make generate-flutter-client
Requires openapi-generator (brew install openapi-generator).
-
Commit both openapi.json and the regenerated files in app/packages/assistant_api/ together with the API change in the same commit (or a follow-up commit in the same PR).
What Counts as an API Change
- Adding, removing, or renaming a route
- Changing request body or query parameter types
- Changing response body types or status codes
- Adding or removing authentication/authorization on an endpoint
- Changing streaming vs. non-streaming behavior
Checklist Before Committing
