feat: blocking reqwest client generator (#20)

Author: dotkas

Cargo.lock

@@ -23,7 +23,8 @@ package: apimodel # informational
 output: models.rs # output path (overridden by -o)
 generate:
   models: true
-  std-http-server: true # also emit an axum server interface
+  std-http-server: true # emit an axum server interface, or…
+  client: true # …a blocking reqwest client (server wins if both are set)
 ```
 
 `import-mapping` maps a referenced spec file to the Rust module its schemas are
@@ -215,6 +216,62 @@ faithfully rather than emit subtly wrong code.
   the same operation (multipart needs its own extractor and cannot join the
   `Content-Type` dispatch).
 
+## Client generation
+
+Setting `generate.client` emits a blocking [`reqwest`] client alongside the
+models. Like the server, the output is typed-only and driven by the same
+internal representation, but it depends solely on `reqwest`, `serde`, and the
+generated models — never `axum`:
+
+- a `struct Client` holding a `base_url` and a `reqwest::blocking::Client`, with
+  `Client::new(base_url)` (builds a default HTTP client) and
+  `Client::with_client(base_url, http)` (accepts a preconfigured client, e.g.
+  with timeouts);
+- one method per operation returning `Result<<Op>Response, ClientError>`, whose
+  arguments are the path parameters, a generated query-parameter struct, a
+  generated header-parameter struct, a generated cookie-parameter struct, and the
+  request body (each present only when the operation declares it);
+- a response `enum` per operation with one variant per documented status code
+  (mirroring the server's shape but carrying `reqwest::StatusCode` for
+  `default`/range variants), plus a `ClientError` enum (`Http(reqwest::Error)`
+  for transport/decoding failures, `UnexpectedStatus(reqwest::StatusCode)` for a
+  status the operation does not declare).
+
+Because the client cannot assume the server honoured the contract, response
+header fields are always `Option<T>` and parsed best-effort, even for headers the
+spec marks required.
+
+A client crate needs `reqwest = { version = "0.12", features = ["blocking",
+"json"] }`. The `json` feature is required when an operation sends a JSON request
+body and/or decodes a JSON response body.
+
+**Supported**
+
+- **Path, query, header, and cookie parameters** — the same scalar/array rules as
+  the server. Query scalars and arrays (repeated keys, `style: form`,
+  `explode: true`) are appended per field; headers and cookies are set from the
+  generated input structs.
+- **Request bodies** — JSON (via `reqwest`'s `.json()`), form
+  (`application/x-www-form-urlencoded`, via `.form()`), and `text/plain` (a raw
+  string body with an explicit `Content-Type`).
+- **Responses** — fixed status codes, `default`, and ranges (`5XX`), decoding a
+  JSON or `text/plain` body into the matching enum variant, along with declared
+  response headers.
+
+**Rejected / deferred** (an error, never mis-generated)
+
+- A `multipart/form-data` request body (no multipart client encoder yet).
+- A request body that declares two or more content types (negotiated request
+  bodies are server-only for now).
+- A response that declares two or more content types (negotiated responses are
+  server-only for now).
+- A form (`application/x-www-form-urlencoded`) _response_ body.
+
+Enabling both `std-http-server` and `client` emits the server (the client is a
+follow-up once multipart and negotiated bodies are supported on the client side).
+Path parameters are substituted verbatim without percent-encoding, which is safe
+for the scalar values the generator accepts.
+
 ## Coverage
 
 Every OpenAPI 3 schema element is deliberately catalogued — supported, ignored,
@@ -239,3 +296,4 @@ the unknown.
 [`quote`]: https://crates.io/crates/quote
 [`syn`]: https://crates.io/crates/syn
 [`prettyplease`]: https://crates.io/crates/prettyplease
+[`reqwest`]: https://crates.io/crates/reqwest

README.md

@@ -26,13 +26,14 @@ syn = { version = "2.0.118", features = ["full"] }
 
 [dev-dependencies]
 # chrono/uuid only type-check the generated model outputs (which reference
-# them); axum type-checks the generated server output; openapiv3 backs the
-# coverage-matrix anchor in tests/coverage.rs. None are needed by the generator
-# itself.
+# them); axum type-checks the generated server output; reqwest type-checks the
+# generated client output; openapiv3 backs the coverage-matrix anchor in
+# tests/coverage.rs. None are needed by the generator itself.
 axum = { version = "0.8.9", features = ["multipart"] }
 axum-extra = { version = "0.12.6", features = ["query", "cookie"] }
 chrono = { version = "0.4.45", features = ["serde"] }
 openapiv3 = "2.2.0"
+reqwest = { version = "0.12.28", default-features = false, features = ["blocking", "json"] }
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = "1.0.150"
 uuid = { version = "1.23.4", features = ["serde"] }

crates/oapi-codegen/Cargo.toml

@@ -41,6 +41,9 @@ pub struct Generate {
     /// Generate an axum server interface from the spec's paths.
     #[serde(default)]
     pub std_http_server: bool,
+    /// Generate a blocking `reqwest` client from the spec's paths.
+    #[serde(default)]
+    pub client: bool,
     /// Embed the spec into the generated code (not yet implemented).
     #[serde(default)]
     pub embedded_spec: bool,

crates/oapi-codegen/src/config.rs

@@ -6,6 +6,7 @@
 
 mod axum;
 mod models;
+mod reqwest;
 
 use proc_macro2::TokenStream;
 use quote::quote;
@@ -26,6 +27,16 @@ pub trait ServerEmitter {
     fn emit(&self, service: &Service) -> Result<Vec<TokenStream>>;
 }
 
+/// Emits a client for a lowered [`Service`] as top-level token items.
+///
+/// One implementation per target HTTP library; `ReqwestClient` is the only one
+/// today.
+pub trait ClientEmitter {
+    /// Emit the client items (error type, `Client` struct, per-operation methods,
+    /// and the response types they return).
+    fn emit(&self, service: &Service) -> Result<Vec<TokenStream>>;
+}
+
 /// Header prepended to every generated file.
 const HEADER: &str = "// Code generated by oapi-codegen-rust. DO NOT EDIT.\n\n";
 
@@ -46,6 +57,13 @@ pub fn emit_with_service(module: &Module, service: &Service) -> Result<String> {
     return render(&items);
 }
 
+/// Render a module's models followed by the blocking `reqwest` client.
+pub fn emit_with_client(module: &Module, service: &Service) -> Result<String> {
+    let mut items = module_items(module)?;
+    items.extend(reqwest::ReqwestClient.emit(service)?);
+    return render(&items);
+}
+
 /// Lower every IR item in a module into its token stream.
 fn module_items(module: &Module) -> Result<Vec<TokenStream>> {
     let mut items = Vec::with_capacity(module.items.len());