fix(website): rebuild the API reference from the generated schema - #3281

Issue

The API reference on anthias.screenly.io is a snapshot of website/data/openapi.yaml committed once during the Hugo migration and never regenerated. Nothing keeps it current:

• generate-openapi-schema.yml uploads anthias-api-schema.json as a workflow artifact and stops — no commit, no push, nothing downstream consumes it.
• deploy-website.yaml fetches marketing screenshots and rpi-imager.json, but never the schema.

So the published reference has been frozen while the API moved on. Measured against a schema generated from current master, it was missing 9 endpoints and 8 component schemas:

Field-level, it also predates play_days / play_time_from / play_time_to, prefer_dark_mode, verify_ssl, and the four display_power_* schedule fields.

The old snapshot is a strict subset of the generated one — nothing was in it that is not in the fresh schema — so it was never hand-curated, just stale.

Changes

Data file. website/data/openapi.yaml → website/data/openapi.json, generated off current master. Hugo resolves site.Data.openapi from either extension, so layouts/_default/api.html is untouched and no conversion step is needed. The two must not coexist, hence the delete rather than an addition.

Fetch on deploy. A new step pulls the anthias-api-schema artifact from the latest successful master run of the schema workflow and overwrites the committed copy before hugo runs, in the shape the Fetch marketing screenshots step already established.

The soft/hard-fail split is deliberate and differs from that step: a missing run is a soft fail, because the committed file is a real fallback and shipping a slightly stale page beats failing the deploy. A corrupt artifact is not, because it would replace a good file with a bad one — the JSON is validated into a temp file and only moved into place once it parses and carries paths and components.schemas, both of which api-schema.html dereferences when resolving a $ref. Without that assert a truncated download renders a blank page instead of failing.

Trigger. The fetch step alone only makes freshness possible. An API-only commit touches no website/** path, so the existing filter never fires and the page drifts again — which is how it got a year behind. The deploy now also chains off workflow_run for Generate OpenAPI Schema on master, guarded so a failed or cancelled schema run cannot trigger a deploy that would silently republish the committed fallback.

⚠️ This is the one judgement call worth a second opinion: generate-openapi-schema.yml runs on nearly every non-website master push, so the site will now redeploy on most merges rather than only on website changes and releases. That is the price of the page never being stale. Drop the workflow_run block if you would rather bound deploy frequency and accept refresh-on-next-website-change.

Layout fix. api-schema.html printed a union type straight into the template, so /api/v2/info's display_power rendered as Go's [string null]. The frozen snapshot happened to contain no multi-type field, so shipping an accurate schema is what surfaced it. Now joined to string | null, matching the | null suffix the nullable branch already renders.

Testing

Built the site locally with the same Hugo version CI pins (0.157.0 extended):

• 22 pages built, no errors.
• The previously-missing endpoints and the display_power_* fields render on /api/.
• $ref resolution works against the new file (DisplayPowerViewSerializerMixin resolves in 5 places).
• display_power renders string | null; a sweep for remaining [... ...] slice artifacts across the page returns nothing.
• bun run llms:generate still indexes 19 pages.
• actionlint 1.7.7 clean on deploy-website.yaml.

Not exercised: the fetch step itself, which only runs on a master push — it cannot execute on a PR. Its gh run list / gh run download calls are copied from the working screenshots step, and the same run_id lookup was run by hand against this repo while preparing the committed schema.

Checklist

• I have performed a self-review of my own code.
• New and existing unit tests pass locally and on CI with my changes.
• I have done an end-to-end test for Raspberry Pi devices.
• I have tested my changes for x86 devices.
• I added a documentation for the changes I have made (when necessary).

The device boxes are not applicable: this changes the marketing site build only and ships no code to a device.

🤖 Generated with Claude Code