Expand description
The REST surface as an OpenAPI 3.1 document (#222).
Clients — ariel first — otherwise have
to hand-write every request and response type by reading the guide. This
module publishes the same shapes as a machine-readable contract at
GET /api/openapi.json.
§Why 3.1, and why schemars rather than a spec framework
OpenAPI 3.1 dropped its bespoke schema dialect and adopted JSON Schema
2020-12 wholesale — which is exactly what schemars emits. So the derives on
prospero-types drop into components/schemas untouched. Targeting 3.0
instead would mean running schemars’ downgrade transforms (AddNullable,
RemoveRefSiblings, …), each of which loses something the real type says.
Publishing 3.1 is therefore not a version preference; it is what lets the
document describe the types as they actually are.
The schemas come from the same structs the handlers serialize, so they cannot
drift from the wire. The routes are a hand-written table below, because
axum’s Router cannot be enumerated at runtime — but tests/openapi.rs
scrapes lib.rs for both the paths it registers and the verbs it answers on
each, so a route or method missing from this table fails the build rather
than shipping a spec that quietly lies.
Functions§
- document
- Build the OpenAPI document describing every REST route.
- get_
openapi GET /api/openapi.json— serve the document.