Problem
The OpenAPI spec published at https://diamondlightsource.github.io/smartem-devtools/api/smartem/swagger.json (source: `smartem-devtools/docs/api/smartem/swagger.json`) is ~8 months stale. The committed version is `0.1.dev276+g1b7ed28d6.d20250818`; the current backend generates a spec that differs by ~2349 lines, including entire endpoint/schema families (e.g. `AgentInstructionAcknowledgement*`, large parts of `GridSquare`). This is pre-existing drift — discovered while working on #248 — not caused by that fix.
This is a problem because:
- `smartem-frontend` consumes this URL via Orval (`npm run api:update` pulls from GitHub Pages). It is currently generating against an 8-month-old contract.
- External consumers relying on the "published" spec are looking at ghost endpoints.
- Version drift in `info.version` is severe: frontend has no way to know it's consuming a stale schema.
Root cause
There is no automation to regenerate and publish the spec. The release workflow (`release-smartem-decisions.yml`) builds the Python wheel / Windows exe / Docker image, but does not emit `openapi.json` as an artifact, and does not push it to smartem-devtools.
Proposed fix
- On every stable release (tag `smartem-decisions-v*`), regenerate the OpenAPI spec and commit it to `smartem-devtools/docs/api/smartem/swagger.json` via an automated PR (or direct commit, depending on repo policy).
- As a first step right now, manually regenerate and land a PR in smartem-devtools so current consumers catch up.
- Consider publishing the spec as a release artifact as well, so consumers can pin to a specific API version rather than always tracking `latest`.
Notes
- Spec dump command:
```
SKIP_DB_INIT=true uv run python -c "import logging, json, smartem_backend.api_server as s; logging.disable(logging.CRITICAL); import pathlib; pathlib.Path('swagger.json').write_text(json.dumps(s.app.openapi(), indent=2, sort_keys=True))"
```
- `info.version` comes from `setuptools_scm` via `FastAPI(version=version)` — already correct on release.
Problem
The OpenAPI spec published at https://diamondlightsource.github.io/smartem-devtools/api/smartem/swagger.json (source: `smartem-devtools/docs/api/smartem/swagger.json`) is ~8 months stale. The committed version is `0.1.dev276+g1b7ed28d6.d20250818`; the current backend generates a spec that differs by ~2349 lines, including entire endpoint/schema families (e.g. `AgentInstructionAcknowledgement*`, large parts of `GridSquare`). This is pre-existing drift — discovered while working on #248 — not caused by that fix.
This is a problem because:
Root cause
There is no automation to regenerate and publish the spec. The release workflow (`release-smartem-decisions.yml`) builds the Python wheel / Windows exe / Docker image, but does not emit `openapi.json` as an artifact, and does not push it to smartem-devtools.
Proposed fix
Notes
```
SKIP_DB_INIT=true uv run python -c "import logging, json, smartem_backend.api_server as s; logging.disable(logging.CRITICAL); import pathlib; pathlib.Path('swagger.json').write_text(json.dumps(s.app.openapi(), indent=2, sort_keys=True))"
```