Skip to main content

The OpenAPI document

The server describes its own surface. Every route, parameter and payload schema in one generated document, never hand-maintained.

Fetch it​

curl https://<your-backend-host>/api/openapi.json > openapi.json

The document for the build these docs describe is also served here: /api/openapi.json.

The document is OpenAPI 3.0. It is generated from annotations on the handlers themselves, so a route exists in the document exactly when it exists on the server, and every schema is derived from the same Rust types the server serialises. The response envelope is part of the document: each operation's 200 schema is the full { ok, data, error } body as the wire carries it.

Browse it​

/api/docs on your backend serves an interactive browser over the same document: every route, expandable schemas, and a try-it button that runs real requests against the deployment serving the page.

Generate a client​

The document feeds any standard generator. A typed TypeScript client:

npx openapi-typescript https://<your-backend-host>/api/openapi.json -o dome-api.d.ts

A Python client:

pip install openapi-python-client
openapi-python-client generate --url https://<your-backend-host>/api/openapi.json

Feature-gated routes​

Some routes exist only in builds carrying the matching Cargo feature: the simulator control routes need simulator, and the fleet, link and command routes need mavlink-control. Both build flavours serve the same document; a build without the feature answers those routes with 501 and the document says so on each affected operation.