baya-monorepo/dev/contracts/openapi/README.md

OpenAPI snapshots

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.