feat(server): combined build_router for multi-tag, required-param 400

Two final P5 polish items.

1. Multi-tag combined router. When the picked ops span 2+ tags,
   the generator now emits a top-level
   `build_router<T1, T2, ...>(api1: T1, api2: T2, ...) -> Router`
   alongside the existing per-tag factories. Each `Ti` is bound to
   the matching trait; the body folds the per-tag factories via
   `.merge(...)`. Tag iteration order is alphabetical
   (BTreeMap), so generic ordering is deterministic. Single-tag
   selections still call the per-tag factory directly — no extra
   noise for the common case.

2. Required-param enforcement at the HTTP boundary. Query and
   header parameters marked `required: true` in the spec now
   appear on the trait method as `T` (not `Option<T>`); the
   generated axum handler short-circuits with HTTP 400 and a
   `{"error": "missing required ..."}` JSON body before invoking
   the trait. Handler return type changed from `<Op>Response` to
   `axum::response::Response` so both the early-400 and the
   typed response enum (via IntoResponse) flow through the same
   return signature.

   Side fix: param-enum emitter now falls back to a positional
   name when PascalCase yields an identifier starting with a
   digit (e.g. `bucket_width=1d` → `Variant0`), which the spec
   surfaced via `usage-costs`.

OpenAI example now picks `usage-costs` (different tag, required
`start_time` query) in addition to `createResponse` and
`listInputItems`. AppState now impls both `ResponsesApi` and
`UsageApi`; main wires them through `build_router(state, state)`.
End-to-end verified at the HTTP layer:
  - `GET /organization/costs` → 400 + error JSON
  - `GET /organization/costs?start_time=1700000000` → 200

All 4 example unit tests pass; 318 main suite tests green;
clippy -D warnings clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: lightsofapollo

examples/server-openai-responses/openapi-to-rust.toml

@@ -8,6 +8,9 @@ enable_async_client = false
 
 [server]
 framework = "axum"
-# createResponse exercises the body + SSE path; listInputItems
-# exercises path params + four query params (one of them an enum).
-operations = ["createResponse", "listInputItems"]
+# createResponse  — body + SSE path
+# listInputItems  — path + four optional query params (one is an enum)
+# usage-costs     — required query param (start_time) + lives on a
+#                   different tag, so it also exercises the multi-tag
+#                   combined `build_router` factory.
+operations = ["createResponse", "listInputItems", "usage-costs"]

examples/server-openai-responses/src/main.rs

@@ -23,8 +23,8 @@ use axum::response::sse::Event;
 use futures_util::stream;
 use gen::CreateResponse;
 use gen::server::{
-    CreateResponseResponse, ListInputItemsResponse, ResponsesApi, responses_api_router,
-    sse_response,
+    CreateResponseResponse, ListInputItemsResponse, ResponsesApi, UsageApi, UsageCostsResponse,
+    build_router, sse_response,
 };
 use std::convert::Infallible;
 
@@ -111,9 +111,37 @@ fn sse_event(name: &str, data: &str) -> Result<Event, Infallible> {
     Ok(Event::default().event(name).data(data))
 }
 
+#[axum::async_trait]
+impl UsageApi for AppState {
+    /// `start_time` is `i64` (not `Option`) — the generated handler
+    /// short-circuits with 400 if the client omits it, so by the
+    /// time we get here the value is guaranteed present.
+    async fn usage_costs(
+        &self,
+        start_time: i64,
+        _end_time: Option<i64>,
+        _bucket_width: Option<gen::UsageCostsBucketWidth>,
+        _project_ids: Option<String>,
+        _group_by: Option<String>,
+        _limit: Option<i64>,
+        _page: Option<String>,
+    ) -> UsageCostsResponse {
+        let body: gen::UsageResponse = serde_json::from_value(serde_json::json!({
+            "object": "page",
+            "data": [],
+            "has_more": false,
+            "next_page": "",
+        }))
+        .unwrap_or_else(|e| panic!("UsageResponse must deserialize: {e}; start_time={start_time}"));
+        UsageCostsResponse::Ok(body)
+    }
+}
+
 #[tokio::main]
 async fn main() {
-    let app = responses_api_router(AppState);
+    // Single combined router that takes both trait impls. Each tag's
+    // routes get mounted on the same axum::Router via `.merge()`.
+    let app = build_router(AppState, AppState);
     let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await.unwrap();
     println!("listening on http://{}", listener.local_addr().unwrap());
     axum::serve(listener, app).await.unwrap();
@@ -155,4 +183,14 @@ mod tests {
             .await;
         assert!(matches!(r, ListInputItemsResponse::Ok(_)));
     }
+
+    #[tokio::test]
+    async fn usage_costs_required_param_arrives_as_unwrapped() {
+        // start_time is `i64` not `Option<i64>` — the generated
+        // handler ensures it's always present.
+        let r = AppState
+            .usage_costs(1_700_000_000, None, None, None, None, None, None)
+            .await;
+        assert!(matches!(r, UsageCostsResponse::Ok(_)));
+    }
 }

src/server/codegen.rs

@@ -128,8 +128,6 @@ impl<'a> ServerCodegen<'a> {
     }
 
     fn emit_router(&self, groups: &BTreeMap<String, Vec<&OperationInfo>>) -> TokenStream {
-        // For now we emit one Router factory per tag. Multi-tag specs
-        // get one factory each; users `.merge()` them at the call site.
         let factories: Vec<TokenStream> = groups
             .iter()
             .map(|(tag, ops)| self.emit_router_for_trait(tag, ops))
@@ -142,6 +140,17 @@ impl<'a> ServerCodegen<'a> {
             .filter_map(|op| self.emit_query_struct(op))
             .collect();
 
+        // When the picked operations span multiple tags, emit a
+        // top-level `build_router(impl1, impl2, ...)` that takes one
+        // generic per trait and `.merge()`s the per-tag factories.
+        // For a single-tag selection this is unnecessary noise — the
+        // user calls the per-tag factory directly.
+        let combined = if groups.len() > 1 {
+            Some(self.emit_combined_router(groups))
+        } else {
+            None
+        };
+
         quote! {
             //! Router factories — one per trait. Each takes any
             //! `T: <TraitName> + Clone + Send + Sync + 'static` and
@@ -159,6 +168,71 @@ impl<'a> ServerCodegen<'a> {
             #(#query_structs)*
 
             #(#factories)*
+
+            #combined
+        }
+    }
+
+    fn emit_combined_router(&self, groups: &BTreeMap<String, Vec<&OperationInfo>>) -> TokenStream {
+        // Stable ordering: BTreeMap iteration is already alphabetical
+        // by tag, which gives us deterministic generic ordering across
+        // generator runs.
+        let entries: Vec<(syn::Ident, syn::Ident, syn::Ident)> = groups
+            .keys()
+            .enumerate()
+            .map(|(i, tag)| {
+                let trait_ident = trait_ident_for_tag(tag);
+                let factory = format_ident!("{}_router", trait_ident.to_string().to_snake_case());
+                let generic = format_ident!("T{}", i + 1);
+                (trait_ident, factory, generic)
+            })
+            .collect();
+
+        let generics: Vec<&syn::Ident> = entries.iter().map(|(_, _, g)| g).collect();
+        let args: Vec<TokenStream> = entries
+            .iter()
+            .map(|(trait_ident, _, g)| {
+                let arg_ident = format_ident!("{}", trait_ident.to_string().to_snake_case());
+                quote! { #arg_ident: #g }
+            })
+            .collect();
+        let bounds: Vec<TokenStream> = entries
+            .iter()
+            .map(|(trait_ident, _, g)| {
+                quote! { #g: #trait_ident + Clone + Send + Sync + 'static }
+            })
+            .collect();
+
+        // Fold the factories: `factory1(arg1).merge(factory2(arg2)).merge(...)`.
+        let first = &entries[0];
+        let first_arg = format_ident!("{}", first.0.to_string().to_snake_case());
+        let first_factory = &first.1;
+        let rest = entries
+            .iter()
+            .skip(1)
+            .map(|(trait_ident, factory, _)| {
+                let arg = format_ident!("{}", trait_ident.to_string().to_snake_case());
+                quote! { .merge(#factory(#arg)) }
+            })
+            .collect::<Vec<_>>();
+
+        let trait_names: Vec<String> = entries.iter().map(|(t, _, _)| t.to_string()).collect();
+        let doc = format!(
+            " Combined router spanning {} traits: {}.",
+            entries.len(),
+            trait_names.join(", "),
+        );
+
+        quote! {
+            #[doc = #doc]
+            pub fn build_router<#(#generics),*>(
+                #(#args),*
+            ) -> ::axum::Router
+            where
+                #(#bounds),*
+            {
+                #first_factory(#first_arg) #(#rest)*
+            }
         }
     }
 
@@ -235,42 +309,87 @@ impl<'a> ServerCodegen<'a> {
         }
 
         // Query parameters — extract via a per-op `<Op>Query` struct
-        // (emitted in the same router.rs above). Each query param
-        // appears in the trait method as `Option<T>`.
+        // (emitted in the same router.rs above). Required params are
+        // unwrapped here (short-circuit 400 if missing) so the trait
+        // method sees a `T` rather than `Option<T>`.
         let query_params: Vec<&_> = op
             .parameters
             .iter()
             .filter(|p| p.location == "query")
             .collect();
+        let mut required_query_checks: Vec<TokenStream> = Vec::new();
         if !query_params.is_empty() {
             let query_ident = format_ident!("{}Query", op.operation_id.to_pascal_case());
             extractors.push(quote! {
                 ::axum::extract::Query(__q): ::axum::extract::Query<#query_ident>
             });
             for p in &query_params {
                 let f = format_ident!("{}", p.name.to_snake_case());
-                call_args.push(quote! { __q.#f });
+                let wire = p.name.as_str();
+                if p.required {
+                    let missing_msg = format!("missing required query parameter `{wire}`");
+                    required_query_checks.push(quote! {
+                        let #f = match __q.#f {
+                            Some(v) => v,
+                            None => return ::axum::response::IntoResponse::into_response(
+                                (
+                                    ::axum::http::StatusCode::BAD_REQUEST,
+                                    ::axum::Json(::serde_json::json!({
+                                        "error": #missing_msg
+                                    })),
+                                )
+                            ),
+                        };
+                    });
+                    call_args.push(quote! { #f });
+                } else {
+                    call_args.push(quote! { __q.#f });
+                }
             }
         }
 
         // Header parameters — extract via HeaderMap and read each
-        // header by name. Surface as Option<String> regardless of
-        // declared type (typed conversions can be re-added later).
+        // header by name. Required headers short-circuit with 400 if
+        // missing or non-UTF-8.
         let header_params: Vec<&_> = op
             .parameters
             .iter()
             .filter(|p| p.location == "header")
             .collect();
+        let mut required_header_checks: Vec<TokenStream> = Vec::new();
         if !header_params.is_empty() {
             extractors.push(quote! { __headers: ::axum::http::HeaderMap });
             for p in &header_params {
                 let wire = p.name.as_str();
-                call_args.push(quote! {
-                    __headers
-                        .get(#wire)
-                        .and_then(|v| v.to_str().ok())
-                        .map(::std::string::String::from)
-                });
+                let ident = format_ident!("{}", header_param_ident(&p.name));
+                if p.required {
+                    let missing_msg = format!("missing required header `{wire}`");
+                    required_header_checks.push(quote! {
+                        let #ident = match __headers
+                            .get(#wire)
+                            .and_then(|v| v.to_str().ok())
+                            .map(::std::string::String::from)
+                        {
+                            Some(v) => v,
+                            None => return ::axum::response::IntoResponse::into_response(
+                                (
+                                    ::axum::http::StatusCode::BAD_REQUEST,
+                                    ::axum::Json(::serde_json::json!({
+                                        "error": #missing_msg
+                                    })),
+                                )
+                            ),
+                        };
+                    });
+                    call_args.push(quote! { #ident });
+                } else {
+                    call_args.push(quote! {
+                        __headers
+                            .get(#wire)
+                            .and_then(|v| v.to_str().ok())
+                            .map(::std::string::String::from)
+                    });
+                }
             }
         }
 
@@ -291,21 +410,28 @@ impl<'a> ServerCodegen<'a> {
             }
         }
 
-        let response_ty = format_ident!("{}Response", op.operation_id.to_pascal_case());
-
+        let _ = format_ident!("{}Response", op.operation_id.to_pascal_case());
         // Keep referencing trait_ident so the where-bound name is
         // visible to downstream readers — clippy would otherwise flag
         // it as unused in some configurations.
         let _ = trait_ident;
 
+        // Handler returns `axum::response::Response` so the required-
+        // param short-circuit (400 BadRequest) and the trait method's
+        // typed response enum (via IntoResponse) can both flow out
+        // through the same return type.
         quote! {
             async fn #handler_ident<T>(
                 #(#extractors),*
-            ) -> #response_ty
+            ) -> ::axum::response::Response
             where
                 T: super::api::#trait_ident + Clone + Send + Sync + 'static,
             {
-                api.#trait_method(#(#call_args),*).await
+                #(#required_query_checks)*
+                #(#required_header_checks)*
+                ::axum::response::IntoResponse::into_response(
+                    api.#trait_method(#(#call_args),*).await,
+                )
             }
         }
     }
@@ -387,22 +513,25 @@ impl<'a> ServerCodegen<'a> {
             if p.location == "query" {
                 let ident = format_ident!("{}", p.name.to_snake_case());
                 let ty = parse_type(&p.rust_type);
-                // All query params are Option<T> on the trait — the
-                // typed Query struct generated alongside the trait
-                // populates None for absent keys regardless of the
-                // spec's `required: true`. Validation moves to the
-                // user's impl (return BadRequest if missing).
-                params.push(quote! { #ident: ::std::option::Option<#ty> });
+                // Required query params land as `T`; the handler
+                // validates presence and returns 400 if absent, so
+                // by the time the trait method sees the value it
+                // must be Some. Optional → `Option<T>`.
+                if p.required {
+                    params.push(quote! { #ident: #ty });
+                } else {
+                    params.push(quote! { #ident: ::std::option::Option<#ty> });
+                }
             }
         }
         for p in &op.parameters {
             if p.location == "header" {
                 let ident = format_ident!("{}", header_param_ident(&p.name));
-                // Headers are surfaced as Option<String>; required
-                // headers are still Option here for the same reason
-                // as query params (deserialization vs. trait
-                // signature stability).
-                params.push(quote! { #ident: ::std::option::Option<String> });
+                if p.required {
+                    params.push(quote! { #ident: String });
+                } else {
+                    params.push(quote! { #ident: ::std::option::Option<String> });
+                }
             }
         }
         if let Some(body) = body_type(op) {
@@ -629,10 +758,16 @@ fn emit_param_enum(name: &str, values: &[String]) -> TokenStream {
         .enumerate()
         .map(|(i, raw)| {
             let pascal = raw.to_pascal_case();
-            // Empty-string or pure-symbol values can collapse to ""
-            // after PascalCase; backstop with a positional name so
-            // the enum still compiles.
-            let v_name = if pascal.is_empty() {
+            // PascalCase can produce an empty string (pure-symbol
+            // input) or an identifier starting with a digit
+            // (e.g. `1d` stays `1d`) — both invalid as Rust idents.
+            // Fall back to a positional name so the enum compiles.
+            let starts_with_digit = pascal
+                .chars()
+                .next()
+                .map(|c| c.is_ascii_digit())
+                .unwrap_or(true);
+            let v_name = if pascal.is_empty() || starts_with_digit {
                 format!("Variant{i}")
             } else {
                 pascal