54 lines
3.2 KiB
Markdown
54 lines
3.2 KiB
Markdown
---
|
|
id: "bug-1966"
|
|
status: "fixed"
|
|
status_updated: "2026-10-10"
|
|
status_note: ""
|
|
component: "apiserver"
|
|
severity: "noise"
|
|
timestamp: "2026-10-10T10:16:16Z"
|
|
last_seen: "2026-10-10T10:16:16Z"
|
|
occurrences: 1
|
|
files: ["src/frontend/apiserver/controllers/hosts.go", "src/frontend/apiserver/docs/swagger.yaml"]
|
|
tags: ["apiserver", "docs", "swagger"]
|
|
related: []
|
|
fix_commits: ["f7fef278"]
|
|
gitea_issue: 397
|
|
gitea_synced_status: "fixed"
|
|
gitea_synced_hash: "bac0daa132f7"
|
|
---
|
|
|
|
# bug-1966: apiserver swagger generation fails on hosts.go models.Error; published swagger is a stale stub
|
|
|
|
## Description
|
|
**Observed:** (source reading; follow-up of the 2026-10-10 P0 fixes (bug-1936..1957))
|
|
`swag init -g cmd/main.go` fails: `ParseComment error in controllers/hosts.go for comment: '// @Failure 400 {object} models.Error': cannot find type definition: models.Error`. `docs/swagger.yaml` is a 212-line stub last generated before the meson merge (no job-control endpoints).
|
|
|
|
**Expected:** Swagger generates from the annotations and the published spec covers the API.
|
|
**Impact:** API documentation missing/stale.
|
|
**Found by:** follow-up of the 2026-10-10 P0 fixes (bug-1936..1957)
|
|
## Environment
|
|
- OS: no /etc/os-release; Docker container; NixOS kernel; kernel Linux 6.18.33 x86_64
|
|
- libc: glibc 2.42-47 (interpreter /nix/store/wb6rhpznjfczwlwx23zmdrrw74bayxw4-glibc-2.42-47/lib/ld-linux-x86-64.so.2)
|
|
- Toolchain: gcc (GCC) 15.2.0, meson 1.9.1
|
|
- Build: asan (xce.build)
|
|
- Code: scheduler-framework @ 19be145d-dirty
|
|
- Deployment: any (found by source reading; confirmed by the RED test of the fix)
|
|
|
|
## Reproduction
|
|
1. `cd src/frontend/apiserver && swag init -g cmd/main.go -o /tmp/x`: fails as above.
|
|
- Frequency: deterministic (by code reading; confirmed by the RED test of the fix)
|
|
- Evidence: the code sites quoted in Description; no logs kept.
|
|
## Root cause
|
|
Swag annotations in `controllers/hosts.go` and `controllers/jobs.go` named non-existent types (`models.Error`, `ErrorResponse`, `JobsResponse`, `JobSignalRequest`, `JobControlResponseSummary`), had malformed `@Param`/`@Failure` lines and wrong `/api/v1` paths, and no general API info existed. Pre-existing.
|
|
|
|
## Fix
|
|
Errors use `JsonErrStruct` (what `ReturnError` writes), success `JsonStruct`; bodies use `models.JobSubmitRequest`, `JobControlJobIDRequest`, `JobControlRequest`; paths match the routes; `@BasePath /xce/v1` and general info in `cmd/main.go`; `docs/docs.go`, `swagger.json`, `swagger.yaml` regenerated with `swag init -g cmd/main.go -o docs`. Only hosts and jobs handlers are annotated so far.
|
|
|
|
## Verification
|
|
- Test: RED: `swag init -g cmd/main.go` failed with `ParseComment error in file .../controllers/hosts.go ... models.Error: cannot find type definition`; GREEN: swag runs cleanly and the spec lists `/hosts`, `/jobs`, `/jobs/create`, `/jobs/{jobids}`, `/jobs/{jobids}/control`, `/jobs/control`; `cmd` (imports docs) tests pass.
|
|
- Suites: `xce-build.sh all asan xce.build --incremental` on the merged branch, 2026-10-10: C suites Ok 157 / Fail 0; frontend Go tests ok (the build now also runs apiserver cmd, middleware, models and router)
|
|
- Live: n/a: unit/fixture-level verification; no live deployment was run
|
|
|
|
## References
|
|
- Fix commits: `f7fef278` (on `scheduler-framework`)
|
|
- Found as a follow-up of the 2026-10-10 P0 fixes (bug-1936..1957)
|