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

typed_openapi/
lib.rs
