typed-openapi

Typed Rust calls and a clap command tree, both built from one OpenAPI document, with every write behind a dry-run gate.

What comes out is api.get_voucher(5)?.send(&client)? returning your own Voucher, and toy vouchers get --id 5 on a command line nobody wrote. What goes in is the vendor's document plus OpenAPI Overlay 1.1 documents holding your corrections to it. This is not a typed model of an OpenAPI document — for that, use openapiv3.

$ toy vouchers create --total 12.50 --currency EUR --status open  # operations at the root
POST /vouchers HTTP/1.1
host: localhost:9999
content-type: application/json

{"total":"12.50","currency":"EUR","status":"open"}

dry run: nothing was sent. Add --commit to send it.

Two consumers, one document

The Rust caller gets owned types and one method per operation, with a newtype wherever the document names a rule — Voucher.currency is a Currency and cannot be built out of something that is not an ISO 4217 code — and a type of your own wherever it cannot: Voucher.total is a fixed-point Money, which no OpenAPI document has a way to describe.

The CLI consumer gets a two-level tree — one subcommand per resource the document's paths name, one per operation under it, so PUT /vouchers/{id} is vouchers update whatever the vendor called it — with flags from the parameters and the request body, and dynamic shell completion. Mount it under raw, under any other name, or as the whole CLI: two calls either way, in docs/cli.md.

Both go through the same request builder, so the CLI and the typed caller cannot disagree about what an operation is — and both run the document's pattern on the same regex engine, so they cannot disagree about what a value is either:

$ toy vouchers create --total 1,50 --currency EUR --status open
error: invalid value '1,50' for '--total <STRING>': `1,50` does not match ^-?[0-9]+(\.[0-9]{1,2})?$

Every rule the document states about a value is enforced, in the document's own numbers — pattern, the lengths, the bounds, multipleOf — on both roads. What that costs is a fifth of the binary: docs/validation.md.

The gate

A read runs on sight. A write prints the exact bytes it would have sent and stops, until --commit. Which operations write is the document's answer rather than a guess from the HTTP method: a GET that stores a PDF is marked x-cli-writes in your Overlay and is gated like any POST. The gate is default-closed, and an operation the document does not describe has no subcommand at all.

One word is not always enough. An operation that cannot be undone, or that reaches a third party, names its own gates in the document: x-cli-gates: [enshrine] grows a required --enshrine demanded beside --commit, so the hazard is typed out before the request is built.

This matters most when the CLI's user is an agent, which has to learn caution from the tool rather than bring it.

The bless step

One command turns the vendor's document and your Overlays into four committed files: the corrected document, the schemas as Rust types, one typed wrapper per operation, and the document reduced to what a command line needs. A shipped binary reads that reduction — it parses no YAML and links no OpenAPI object model.

Corrections come in layers, applied in the order you name them, so the one that repairs the vendor's mistakes stays a document worth handing back to the vendor while the one that marks operations for a command line sits above it. The generator ships inside this crate behind the generate feature, so your xtask is about twenty lines — see docs/generating.md.

A vendor revision that moves something you corrected fails the bless step, naming the layer it is in, rather than silently overwriting the correction; one that withdraws an operation or a field your code names fails the compiler. What is not caught is listed in docs/drift.md beside what is.

Features

Each feature adds and removes whole items and never changes one, so a match exhaustive in one build is exhaustive in all.

No HTTP client, in any combination. The seam is a two-method trait over http::Request<Vec<u8>>, and an adapter is about ten lines. The default feature set is 30 crates; 21 without clap. The one client the crate does ship is Recorder, which sends nothing and answers from a script, so a test of anything above the seam needs no socket and no fixture server. Both are docs/client.md.

What it does not do

• No authentication. Sign the http::Request in your adapter.
• No oneOf / allOf / anyOf request bodies. A nested body is --json-body FILE; per-field flags exist only for flat ones.
• No object parameters. A list of scalars is a repeatable flag, laid out by its own style and explode. An object, an in: cookie, a content-described parameter and an unserialisable style carry no flag: each is named on its subcommand's help, and refuses the document only where the document requires it.
• No async CLI. The command tree is sync; AsyncClient is for the typed caller.
• No check on a whole-body file. --json-body FILE is held to being JSON and no further; holding its content to a schema needs the generated struct, which only your crate can name.
• A regex engine in every binary. Enforcing pattern costs one and no feature removes it: 810 KB of the example's 4.6 MB stripped binary.
• The reduced model is a binary blob, diffable only by regenerating it.
• Rust 1.88, in every feature set, set by the regex engine. Stable throughout — only this repository's own recipes want nightly.

Where to go next

typed-openapi/ is the published crate and the only thing on crates.io; everything under examples/toy/ is one adoption of it, held by the same just gate CI runs — formatting, clippy, rustdoc, every feature combination, the tests, and the crate built from its own tarball.

Licensed under either of Apache-2.0 or MIT, at your option.