hamid
35 lines
1.9 KiB
Markdown
35 lines
1.9 KiB
Markdown
# 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/`](../../../docs/integration/openapi/README.md) (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.
|