OpenAPI snapshot

The machine contract. The server generates it with NSwag; this folder holds the published snapshot so the client can generate or verify types without booting the backend.

Last verified: 2026-07-29 against commit c99e3f4 (server code last changed in 5885280, 2026-07-28).


File	`swagger.v1.json`
Taken	2026-07-29
Commit	`c99e3f4`
Paths	178
Operations	186
Component schemas	339
Generator	NSwag v14.7.1.0 · OpenAPI 3.0.0
Size	612 K

How to regenerate

The API binds plain HTTP on port 5002 (launchSettings.json), despite what most prose in this repo says — see contradiction C-3. Use whatever port you bind; the document is the same.

cd server
ASPNETCORE_ENVIRONMENT=Development dotnet run \
  --project src/API/Baya.Web.Api/Baya.Web.Api.csproj

# from another shell, once "Now listening" appears:
curl -s --noproxy '*' http://127.0.0.1:5002/swagger/v1/swagger.json \
  -o docs/integration/openapi/swagger.v1.json

Two things that cost time the first run:

Booting in Development migrates and seeds against the DB in appsettings.Development.json — currently a remote SQL Server. First boot takes ~40 s and logs Demo world already seeded — no-op. when the world is present.
--noproxy '*' matters. With a proxy configured in the environment, curl to localhost returns 502 rather than the document.

Then update the table above — date, commit, and endpoint count — in the same change. A snapshot whose provenance is unrecorded is what this chain exists to stop.

Scope

v1 only. The old README claimed the server publishes documents v1 and v1.1, but only v1 has ever been committed and v1.1 was not fetched during the phase 0 survey. UNVERIFIED: check /swagger/v1.1/swagger.json when the server is next up (contradiction C-9).

The human contract

The prose half — one file per domain — lands in ../domains/ in phase 2. The two must agree: this JSON is the wire truth, the markdown explains it. When they disagree, the JSON wins and the markdown is wrong.