Geti Openapi Sync
Developmentgeti-openapi-syncGeti Openapi Sync is an Agent Skill for development published in the open-edge-platform/geti repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Regenerate and validate the OpenAPI contract between `application/backend/` and `application/ui/`. Use when backend endpoints, schemas, request or response models, or API surface change, or when `application/ui/src/api/openapi-spec.json` or `openapi-spec.d.ts` is stale. Handles backend spec generation, UI spec placement, TypeScript type regeneration, and the smallest backend and UI checks needed to confirm the contract still matches.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/open-edge-platform/geti/blob/HEAD/skills/application/geti-openapi-sync/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/geti-openapi-sync, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Geti OpenAPI Sync
Goal
- Keep backend OpenAPI output and UI generated API types in sync.
- Prefer regeneration over manual edits to generated JSON or
.d.tsfiles.
Preferred Workflow
- If the backend is not already running, generate the spec from
application/backend/withjust gen-api-spec --output-path ../ui/src/api/openapi-spec.jsonon Unix-like shells, orjust gen-api-spec --output-path ..\\ui\\src\\api\\openapi-spec.jsonon Windows. - If the backend is already running on
http://localhost:7860, work fromapplication/ui/and runnpm run update-spec. - If only the JSON spec changed locally, run
npm run build:apifromapplication/ui/to regeneratesrc/api/openapi-spec.d.ts. - Run
npm run format:checkandnpm run type-checkinapplication/ui/, then the narrowest backend or UI tests affected by the contract change.
When to Use Each Path
- Use direct backend generation when working offline, in CI-like flows, or before the server is runnable.
- Use
npm run update-specwhen actively iterating with a local backend server. - Use
$geti-backend-devfor backend fixes if generation exposes schema problems. - Use
$geti-ui-devfor UI changes that consume the regenerated types.
Guardrails
- Commit the generated spec and
.d.tstogether when the contract change is intentional. - Do not manually edit
application/ui/src/api/openapi-spec.d.ts. - If generation fails, fix the backend route or schema definitions instead of patching the generated output.