hamid
23 lines
1.2 KiB
Markdown
23 lines
1.2 KiB
Markdown
# 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.
|