OpenAPI

Every mounted command and query is described in an OpenAPI document generated with aide. Payload schemas come from the same Rust types that deserialize requests, so the document cannot drift from the code.

GET/api/openapi.jsonthe document

GET/redirects to the document

What is in it

Element	Source
Command operations	command_engine! metadata: key, title, payload JSON Schema (schemars)
Query operations	The resource interface: fields, presets, filters
Report operations	The report's params and filters
Merged operations	Any ApiRouter passed to app.merge(…), such as RxDB pull and push
Tags	riverbase:command, riverbase:query, riverbase:metadata, plus domain:{ns} and queryset:{ns}

Each operation carries vendor extensions that clients and generators can rely on:

Extension	Meaning
x-kind	Operation kind: command, query, report, metadata
x-api	The API family
x-domain	The namespace
x-command	The command key
x-resources	Resources the command targets
x-scoped	Whether the route takes a scope segment
x-queryset	The query resource

Labels and descriptions

Command payload fields use standard schemars attributes:

payload {
    /// Shown as the field description.
    #[schemars(title = "Title", extend("x-widget" = "text"))]
    title: String,
}

Command-level text comes from title in meta. Command options such as openapi_tag, openapi_internal, and openapi_explorer adjust grouping and visibility.

Per-caller documents

With [riverbase.casbin] omit_inaccessible_openapi = true, each caller's document omits the operations their roles cannot run. A frontend can then build its navigation from the document it receives.

Zones

With api_zone set, only routes whose allowed zones intersect it are registered, and only those appear in the document. One codebase can then serve, for example, a public zone and an admin zone from different deployments.