feat(server): DevX fixes — sse_response helper, end-of-generate hint, --regenerate

Three frictions surfaced while building the OpenAI Responses and
Anthropic Messages examples, all fixed here.

1. SSE construction was verbose: every user had to import axum::Sse +
   KeepAlive, futures-core, futures-util, plus Box::pin the stream.
   Now the generator emits `sse_response(stream)` alongside the
   `ServerEventStream` type alias — wraps any
   `Stream<Item = Result<Event, Infallible>>` and returns the exact
   payload the OkStream variant takes. Both examples updated to use
   it; the streaming branch is now two lines.

2. After `generate` the user had no signpost to the implementation
   step. The CLI now prints a paste-ready impl skeleton naming the
   concrete trait, method, body type, and router function picked
   from the first resolved operation. SSE ops also get a one-line
   hint about `sse_response`.

3. `server add --regenerate` was declared in the planning doc but
   never wired. Now it re-execs the binary in `generate` mode using
   the same compiled artifact — fixes the "add then forget to
   regenerate" footgun.

Verified: 318 lib/integration tests green, clippy -D warnings clean,
both example crates' `cargo test` (unary + SSE branches) still pass.

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

Author: lightsofapollo

examples/server-anthropic-messages/src/main.rs

@@ -27,12 +27,11 @@
 
 pub mod gen;
 
-use axum::response::sse::{Event, KeepAlive, Sse};
+use axum::response::sse::Event;
 use futures_util::stream;
 use gen::CreateMessageParams;
-use gen::server::{MessagesPostResponse, ServerApi, ServerEventStream, server_api_router};
+use gen::server::{MessagesPostResponse, ServerApi, server_api_router, sse_response};
 use std::convert::Infallible;
-use std::time::Duration;
 
 #[derive(Clone)]
 struct AppState;
@@ -99,10 +98,7 @@ fn messages_streaming() -> MessagesPostResponse {
         sse_event("content_block_stop", r#"{"type":"content_block_stop","index":0}"#),
         sse_event("message_stop", r#"{"type":"message_stop"}"#),
     ]);
-    let pinned: ServerEventStream = Box::pin(events);
-    MessagesPostResponse::OkStream(
-        Sse::new(pinned).keep_alive(KeepAlive::new().interval(Duration::from_secs(15))),
-    )
+    MessagesPostResponse::OkStream(sse_response(events))
 }
 
 fn sse_event(name: &str, data: &str) -> Result<Event, Infallible> {

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

@@ -19,12 +19,11 @@
 
 pub mod gen;
 
-use axum::response::sse::{Event, KeepAlive, Sse};
+use axum::response::sse::Event;
 use futures_util::stream;
 use gen::CreateResponse;
-use gen::server::{CreateResponseResponse, ResponsesApi, ServerEventStream, responses_api_router};
+use gen::server::{CreateResponseResponse, ResponsesApi, responses_api_router, sse_response};
 use std::convert::Infallible;
-use std::time::Duration;
 
 #[derive(Clone)]
 struct AppState;
@@ -76,10 +75,10 @@ fn create_response_streaming() -> CreateResponseResponse {
         sse_event("response.output_text.delta", r#"{"delta":"world"}"#),
         sse_event("response.completed", r#"{"id":"resp_demo"}"#),
     ]);
-    let pinned: ServerEventStream = Box::pin(events);
-    CreateResponseResponse::OkStream(
-        Sse::new(pinned).keep_alive(KeepAlive::new().interval(Duration::from_secs(15))),
-    )
+    // `sse_response` is the generated helper — wraps any
+    // `Stream<Item = Result<Event, Infallible>>` so the user
+    // doesn't have to import axum::Sse or `Box::pin` it manually.
+    CreateResponseResponse::OkStream(sse_response(events))
 }
 
 fn sse_event(name: &str, data: &str) -> Result<Event, Infallible> {

src/bin/openapi-to-rust.rs

@@ -86,6 +86,10 @@ enum ServerCommands {
         /// Print the proposed change without writing.
         #[arg(long)]
         dry_run: bool,
+        /// After updating the TOML, immediately run `generate` to
+        /// emit code for the new selectors.
+        #[arg(long)]
+        regenerate: bool,
     },
     /// Remove a selector entry from `[server].operations`.
     Remove {
@@ -277,6 +281,7 @@ async fn run(cli: Cli) -> Result<(), Box<dyn std::error::Error>> {
                         server_files.len(),
                         out.display()
                     );
+                    print_server_hint(&analysis, server_section);
                 }
             }
 
@@ -321,7 +326,8 @@ async fn run(cli: Cli) -> Result<(), Box<dyn std::error::Error>> {
                 config,
                 all_tag,
                 dry_run,
-            } => run_server_add(selector, spec, config, all_tag, dry_run),
+                regenerate,
+            } => run_server_add(selector, spec, config, all_tag, dry_run, regenerate),
             ServerCommands::Remove {
                 selector,
                 config,
@@ -395,6 +401,7 @@ fn run_server_add(
     config: PathBuf,
     all_tag: Option<String>,
     dry_run: bool,
+    regenerate: bool,
 ) -> Result<(), Box<dyn std::error::Error>> {
     let spec_path = resolve_spec_path(spec, &config)?;
     let analysis = load_analysis(&spec_path)?;
@@ -455,12 +462,31 @@ fn run_server_add(
         }
     }
     if !dry_run && !added.is_empty() {
+        let next_step = if regenerate {
+            "Regenerating now..."
+        } else {
+            "Run `openapi-to-rust generate` to emit code."
+        };
         println!(
-            "\n✓ Added {} entr{} to {}. Run `openapi-to-rust generate` to emit code.",
+            "\n✓ Added {} entr{} to {}. {next_step}",
             added.len(),
             if added.len() == 1 { "y" } else { "ies" },
             config.display(),
         );
+        if regenerate {
+            // Re-exec ourselves in `generate` mode against the same
+            // config. We do this via the binary path (current_exe) so
+            // we pick up the same compiled artefact the user is using.
+            let exe = std::env::current_exe()?;
+            let status = std::process::Command::new(exe)
+                .arg("generate")
+                .arg("--config")
+                .arg(&config)
+                .status()?;
+            if !status.success() {
+                return Err(format!("regenerate failed with status {status}").into());
+            }
+        }
     }
     Ok(())
 }
@@ -512,6 +538,74 @@ fn print_add_summary(
     Ok(())
 }
 
+/// Surface a paste-ready impl skeleton at the end of `generate`.
+/// Reads the picked operations from the analysis to name the trait,
+/// method, and body type concretely. Goes to stderr so it doesn't
+/// pollute machine-readable stdout consumers.
+fn print_server_hint(
+    analysis: &openapi_to_rust::SchemaAnalysis,
+    server: &openapi_to_rust::config::ServerSection,
+) {
+    use heck::{ToPascalCase, ToSnakeCase};
+
+    // Pick the first resolved op to ground the skeleton in concrete
+    // names. Showing one is enough — users extrapolate to siblings.
+    let first_op_id = server.operations.first().and_then(|raw| {
+        Selector::parse(raw).ok().and_then(|sel| match sel {
+            Selector::OperationId(id) => Some(id),
+            Selector::MethodPath { method, path } => analysis
+                .operations
+                .values()
+                .find(|op| op.method == method && op.path == path)
+                .map(|op| op.operation_id.clone()),
+            Selector::Tag(t) => analysis
+                .operations
+                .values()
+                .find(|op| op.tags.iter().any(|tag| tag == &t))
+                .map(|op| op.operation_id.clone()),
+        })
+    });
+
+    let Some(first_op_id) = first_op_id else {
+        return;
+    };
+    let Some(op) = analysis.operations.get(&first_op_id) else {
+        return;
+    };
+    let method = op.operation_id.to_snake_case();
+    let response_ty = format!("{}Response", op.operation_id.to_pascal_case());
+    let body_param = match &op.request_body {
+        Some(rb) => match rb.schema_name() {
+            Some(name) => format!(", body: {name}"),
+            None => String::new(),
+        },
+        None => String::new(),
+    };
+    let tag = op.tags.first().cloned().unwrap_or_else(|| "Server".into());
+    let trait_name = format!("{}Api", tag.to_pascal_case());
+    let router_fn = format!("{}_router", trait_name.to_snake_case());
+
+    eprintln!();
+    eprintln!("📝 Next step — implement the trait:");
+    eprintln!();
+    eprintln!("   #[derive(Clone)]");
+    eprintln!("   pub struct AppState {{ /* state goes here */ }}");
+    eprintln!();
+    eprintln!("   #[axum::async_trait]");
+    eprintln!("   impl {trait_name} for AppState {{");
+    eprintln!("       async fn {method}(&self{body_param}) -> {response_ty} {{");
+    eprintln!("           todo!()");
+    eprintln!("       }}");
+    eprintln!("   }}");
+    eprintln!();
+    eprintln!("   // In main():");
+    eprintln!("   let app = {router_fn}(AppState {{ /* … */ }});");
+    eprintln!();
+    if op.supports_streaming {
+        eprintln!("   For streaming, return `{response_ty}::OkStream(sse_response(your_stream))`.");
+    }
+}
+
 fn run_server_remove(
     selector: String,
     config: PathBuf,

src/server/codegen.rs

@@ -348,9 +348,8 @@ impl<'a> ServerCodegen<'a> {
         // need it.
         let stream_alias = if any_streaming {
             quote! {
-                /// Stream payload carried by `*Stream` variants. Build with
-                /// `Box::pin(your_stream)` where each yielded item is a
-                /// pre-constructed `axum::response::sse::Event`.
+                /// Stream payload carried by `*Stream` variants. Each
+                /// yielded item is a pre-built `axum::response::sse::Event`.
                 pub type ServerEventStream = ::std::pin::Pin<
                     Box<
                         dyn ::futures_core::Stream<
@@ -362,6 +361,23 @@ impl<'a> ServerCodegen<'a> {
                             + 'static,
                     >,
                 >;
+
+                /// Wrap any `Stream<Item = Result<Event, Infallible>>` in
+                /// a `Sse<ServerEventStream>` ready to drop into the
+                /// `OkStream` variant. Replaces the
+                /// `Sse::new(Box::pin(...))` dance.
+                pub fn sse_response<S>(stream: S) -> ::axum::response::sse::Sse<ServerEventStream>
+                where
+                    S: ::futures_core::Stream<
+                            Item = ::std::result::Result<
+                                ::axum::response::sse::Event,
+                                ::std::convert::Infallible,
+                            >,
+                        > + ::std::marker::Send
+                        + 'static,
+                {
+                    ::axum::response::sse::Sse::new(Box::pin(stream))
+                }
             }
         } else {
             quote! {}