baya-monorepo/archive/build-chain/contracts/openapi/README.md

OpenAPI snapshots — MOVED to docs/integration/openapi/

⛔ The swagger.v1.json in this folder is the 2026-07-13 snapshot and is stale. The current one is docs/integration/openapi/ (2026-07-29, 178 paths / 186 operations), with its provenance and regeneration steps recorded there.

The claim below that the server "publishes documents v1, v1.1" is literally true and substantively empty: both documents are registered, but all 55 controllers are [ApiVersion("1")], so the v1.1 document contains zero paths (contradiction C-9, resolved in phase 2).

Phase 6 archives this folder. Until then, read it as a record.

---

The server already generates OpenAPI via NSwag (Swagger UI at /swagger, documents v1, v1.1). This folder holds the published swagger.json snapshot(s) so the frontend can generate/verify types without running the backend.

Backend: publish on every API-shipping phase

After adding/changing endpoints and confirming the build, export the OpenAPI document and commit it here as swagger.v1.json (overwrite — git history is the version trail). Typical options:

• Run the API and save GET /swagger/v1/swagger.json to dev/contracts/openapi/swagger.v1.json, or
• Use the NSwag CLI / build target the server already wires to emit the document.

Record in your handoff that the snapshot was refreshed. Keep it in sync with ../domains/*.md — the markdown is the human contract, this JSON is the machine contract; they must agree.

Frontend: consume

Generate types from swagger.v1.json (e.g. an openapi-typescript-style step) or hand-write src/services/{domain}/types.ts to match it. Either way, the wire shapes come from here — not from guessing. Casing/format questions are resolved by this file.

Until the first API-shipping backend phase runs, this folder is empty by design.