wehub-resource-sync
f99010fae1
CI / lint (push) Failing after 1s
CI / frontend (push) Failing after 1s
CI / scripts (push) Failing after 1s
CI / Go Test (ubuntu-latest) (push) Failing after 0s
CI / frontend-node-25 (push) Failing after 1s
CI / docs (push) Failing after 0s
CI / coverage (push) Failing after 0s
CI / e2e (push) Failing after 0s
Docker / build-and-push (push) Failing after 1s
CI / integration (push) Failing after 4m43s
CI / Go Test (windows-latest) (push) Has been cancelled
CI / Desktop Unit Tests (Windows) (push) Has been cancelled
Desktop Artifacts / Desktop Build (Linux (arm64)) (push) Has been cancelled
Desktop Artifacts / Desktop Build (Linux) (push) Has been cancelled
Desktop Artifacts / Desktop Build (Windows) (push) Has been cancelled
Desktop Artifacts (macOS) / Desktop Build (macOS (aarch64)) (push) Has been cancelled
Desktop Artifacts (macOS) / Desktop Build (macOS (x86_64)) (push) Has been cancelled
30 lines
1.4 KiB
Markdown
30 lines
1.4 KiB
Markdown
# Huma API Routes
|
|
|
|
The server API is registered with Huma route groups. Keep each route group
|
|
self-contained so OpenAPI ownership stays close to runtime behavior.
|
|
|
|
## File Ownership
|
|
|
|
- Put route registration, endpoint-specific input types, response wrapper types,
|
|
enums, and handlers in the route group file that owns the path.
|
|
- Keep `internal/server/huma_routes.go` limited to shared Huma plumbing: API
|
|
configuration, route registration helpers, common path/query inputs, error
|
|
conversion, schema naming, SSE/write helpers, and middleware.
|
|
- Move a helper into shared plumbing only when at least two route groups use it
|
|
and it has no domain-specific policy.
|
|
- Do not add new typed handlers to a catch-all API file. Add a new group file
|
|
when a new API area does not fit an existing group.
|
|
|
|
## Compatibility Guardrails
|
|
|
|
When changing route registration or generated client contracts:
|
|
|
|
- Preserve existing paths, methods, status codes, response events, and content
|
|
types unless the change is intentional and covered by tests.
|
|
- Add or update parity tests for JSON bodies, raw downloads, multipart imports,
|
|
SSE terminal events, and error responses touched by the change.
|
|
- Run `npm run generate:api` from `frontend/` and verify generated output only
|
|
changes when the OpenAPI contract intentionally changed.
|
|
- Keep generated frontend code under `frontend/src/lib/api/generated/`; it is
|
|
marked as generated in `.gitattributes` and should not be hand-edited.
|