API Contract And Release Checks
Keep Swagger, generated clients, route backlog, CI, and admin docs aligned.
API Contract And Release Checks
The backend owns the API contract. Swagger is generated from Go annotations, and the route-contract tool compares generated Swagger paths with the cahier-derived route backlog.
Contract Files
| File | Purpose |
|---|---|
backend/docs/api-routes.md | Product route backlog extracted from the backend cahier. |
backend/docs/swagger/swagger.json | Generated OpenAPI JSON. |
backend/docs/swagger/swagger.yaml | Generated OpenAPI YAML. |
backend/docs/api-contract-status.md | Human-readable implemented/missing route comparison. |
backend/docs/api-contract-status.json | Machine-readable route comparison. |
frontend/src/lib/api/client | Generated frontend HeyAPI client. |
dashboard/src/lib/api/client | Generated dashboard HeyAPI client. |
Current status: all 54 expected cahier backlog operations are represented in Swagger. Additional implemented routes include tenant admin CRUD, API keys, webhooks, audit, public verification aliases, agent campaign revocation, and ingest proof polling.
Refresh Commands
From backend/:
make api-contract
Route comparison only:
go run ./cmd/route-contract -write-docs
Backend tests:
go test ./...
Frontend Client Refresh
The frontends should not hand-edit generated clients.
cd frontend
npm run generate:api
npm run check
cd dashboard
pnpm check
pnpm build
CI Expectations
The Gitea workflow is expected to cover:
| Gate | Purpose |
|---|---|
| Migration discipline | SQL migration files are reviewed and migrator image can run. |
| Go tests | Unit/integration coverage for backend services and HTTP behavior. |
| Swagger and HeyAPI freshness | Prevents stale clients and undocumented routes. |
| Security scans | govulncheck, gitleaks, Trivy, and dependency checks where configured. |
| SBOM/provenance | Image supply-chain evidence. |
| Image build/scan/publish | Backend and frontend container delivery. |
| Compose E2E | Full-stack smoke paths with parallel-safe ports. |
Documentation Update Rule
When a change affects operator behavior, update the Hugo admin docs in the same change set. Examples:
| Change | Docs to update |
|---|---|
| New route or changed role | Access-control and relevant admin runbook. |
| New worker or queue | Workers and queues, observability, incidents. |
| New environment variable | Configuration reference and deployment checklist. |
| New migration or storage key layout | Migrations/release and backup/restore. |
| Changed alert | Observability and incident response. |
| Changed production gap state | Backend gap register. |
Build docs before delivering:
cd admin-docs
hugo --gc --minify