# 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`](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.

```bash
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](../../../dev/contracts/openapi/README.md) 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/`](../index.md) 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.