typed_openapi/
lib.rs

1//! <!-- The primer is the repository's README, which is also this crate's
2//! front page on crates.io and docs.rs. What follows it here is the part a
3//! reader wants *after* deciding to use the crate: the map of the API, and
4//! what a feature is allowed to do to it. -->
5#![doc = include_str!("../README.md")]
6//!
7//! # The API
8//!
9//! The six things a caller learns:
10//!
11//! - [`Document`] — the document, corrected and resolved.
12//!   [`Document::from_blob`] takes the reduction back off the bytes
13//!   [`Document::to_blob`] wrote.
14//! - [`Values`] — arguments for one operation, under the document's own names.
15//!   A CLI builds one from `ArgMatches`; a generated wrapper builds one from
16//!   typed arguments.
17//! - [`Invocation`] — an operation and values that satisfy it. Making one is
18//!   the validation; [`Invocation::request`] is then a rendering.
19//! - [`Plan`] — the gate. A read runs on sight; a write runs only once
20//!   confirmed, and until then a dry run prints the exact bytes a confirmed
21//!   run would send.
22//! - `tree::commands` and `tree::dispatch` — the clap tree, and the trip back.
23//! - [`SyncClient`] / [`AsyncClient`] — where the request meets the network.
24//!
25//! The document is data: an operation is a value in a list, not a branch
26//! someone wrote, so there is no chance of the CLI disagreeing with the
27//! document it shipped with, and the tree, the completion and the request
28//! builder all read the same list.
29//!
30//! Reading that list out of YAML is not, however, something a shipped binary
31//! should do on every invocation, and under the default feature set it is not
32//! something a shipped binary compiles. `Document::load` is the expensive door
33//! and `document` is what opens it; [`Document::from_blob`] is the door a
34//! binary uses, and it takes the reduction a bless step already wrote down.
35//!
36//! # What a feature may do
37//!
38//! Every feature adds and removes whole items and never changes one. No type
39//! on this page gains a variant or a field with one, so a caller who matches
40//! an error of this crate exhaustively writes the same match in every build,
41//! and what the docs say about a type they can see is true of every build that
42//! has it.
43//!
44//! `clap` is on by default because most adopters want the command tree; a
45//! crate that only wants typed calls turns it off and links no argument
46//! parser. `document` and `generate` belong to the bless step, and a shipping
47//! binary that enabled either would compile a YAML parser, an OpenAPI object
48//! model and a code generator it can never reach.
49
50#[cfg(feature = "clap")]
51pub mod tree;
52
53#[cfg(feature = "document")]
54pub mod overlay;
55#[cfg(feature = "document")]
56pub mod schema;
57
58#[cfg(feature = "generate")]
59pub mod generate;
60
61pub mod client;
62pub mod model;
63pub mod multipart;
64pub mod names;
65pub mod plan;
66pub mod request;
67pub mod scalar;
68pub mod transport;
69pub mod values;
70
71/// `bon`, for generated code to name the builder macro through.
72///
73/// A generated `ops.rs` writes `#[bon(crate = ::typed_openapi::bon)]`, so the
74/// crate holding it turns the builder on with one feature and adds no
75/// dependency of its own — and the proc-macro version stays the one the
76/// generator emitted syntax for.
77#[cfg(feature = "builder")]
78pub use bon;
79pub use client::{Call, Client, NoContent};
80#[cfg(feature = "document")]
81pub use model::LoadError;
82pub use model::{
83    Body, COMMIT, Document, DocumentError, Effect, Field, JSON_BODY, Location, Operation, Param,
84    RAW_BODY,
85};
86pub use names::{CommandName, kebab};
87pub use plan::{Plan, PlanError};
88/// `regress`, for generated code to name the regex engine through.
89///
90/// A generated `types.rs` enforces a schema's `pattern` inside `FromStr`, and
91/// the generator points every such check at `::typed_openapi::regress`, so the
92/// crate holding the generated code adds no dependency of its own — and the
93/// engine stays the one the generator emitted syntax for, which is the same one
94/// [`Scalar::parse`] runs the command line's values through.
95pub use regress;
96pub use request::{Invocation, ValueError, render};
97pub use scalar::Scalar;
98pub use transport::{AsyncClient, HttpRequest, HttpResponse, Recorder, SyncClient};
99pub use values::{Part, Payload, Values};
typed_openapi/lib.rs

typed_openapi/
lib.rs
