feat(server): trait, response enums, router, SSE, examples (P4 + P5-lite)

Server-side codegen now emits a working axum service for a
user-selected subset of the spec. Trait per tag, status-code-typed
response enum with IntoResponse, conditional OkStream variant for
SSE, per-trait Router factory.

Files emitted to output_dir/server/:
  mod.rs     — re-exports api, errors, router
  api.rs     — `pub trait <Tag>Api { async fn <op>(&self, ...) -> <Op>Response; }`
  errors.rs  — `pub enum <Op>Response { Ok(T), BadRequest(E), ..., OkStream(Sse<S>) }`
               with IntoResponse → (StatusCode, Json) | sse.into_response()
  router.rs  — `pub fn <tag>_api_router<T>(api: T) -> axum::Router`

SSE: when an op's supports_streaming is true, the response enum
gains an OkStream(Sse<ServerEventStream>) variant. ServerEventStream
is a Pin<Box<dyn Stream<Item = Result<Event, Infallible>> + Send>>
alias. User builds the stream and returns the variant; IntoResponse
delegates to axum's Sse.

Two end-to-end examples added:
  examples/server-openai-responses/   — createResponse, both branches
  examples/server-anthropic-messages/ — messages_post, both branches

Both examples implement the conditional `body.stream` pattern: when
stream:true → return OkStream with canned SSE events; otherwise →
return Ok with a JSON body. The Anthropic example ships a small
sse-overlay.json schema extension because the upstream spec omits
text/event-stream on the 200 response (resolves bd:in6).

Each example has unit tests verifying both branches construct
correctly at runtime. The new gated integration test
tests/server_examples_test.rs regenerates code + runs cargo test
against both examples (`cargo test --test server_examples_test --
--ignored`).

Closes openapi-generator-jih (P4 trait + response enums).
Closes openapi-generator-in6 (Anthropic SSE gap).
Partial openapi-generator-cdx (P5 router factory shipped; typed
query/header extractors and model pruning still pending).

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

Author: lightsofapollo

.beads/issues.jsonl

@@ -0,0 +1,3 @@
+target/
+Cargo.lock
+src/gen/

examples/server-anthropic-messages/.gitignore

@@ -0,0 +1,18 @@
+[package]
+name = "server-anthropic-messages"
+version = "0.0.0"
+edition = "2021"
+publish = false
+
+[dependencies]
+axum = "0.7"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tokio = { version = "1", features = ["full"] }
+futures-core = "0.3"
+futures-util = "0.3"
+
+# Pulled in by the generated types — see src/gen/REQUIRED_DEPS.toml
+# after running `openapi-to-rust generate`.
+base64 = "0.22"
+chrono = { version = "0.4", features = ["serde"] }

examples/server-anthropic-messages/Cargo.toml

@@ -0,0 +1,27 @@
+# server-anthropic-messages
+
+End-to-end demo of the server codegen: scaffold `POST /v1/messages`
+from the Anthropic spec, implement the trait, serve it via axum.
+
+```bash
+# From repo root:
+cargo run -p openapi-to-rust -- generate \
+  --config examples/server-anthropic-messages/openapi-to-rust.toml
+
+cargo run --manifest-path examples/server-anthropic-messages/Cargo.toml
+
+# In another shell:
+curl -s http://127.0.0.1:3001/v1/messages \
+  -H 'content-type: application/json' \
+  -d '{"model":"claude-x","max_tokens":50,"messages":[{"role":"user","content":"hi"}]}'
+```
+
+**Streaming caveat.** Anthropic's published OpenAPI spec doesn't
+declare `text/event-stream` on the 200 response, so the generator
+can't emit an `OkStream` variant. Tracked as `openapi-generator-in6`
+— the planned fix is a schema-extension overlay that adds the
+streaming content type, after which this example will gain a
+streaming branch with no manual changes.
+
+The integration test in `tests/server_examples_test.rs` guarantees
+the example keeps building.

examples/server-anthropic-messages/README.md

@@ -0,0 +1,14 @@
+[generator]
+spec_path = "../../specs/anthropic.yaml"
+output_dir = "src/gen"
+module_name = "anthropic"
+# Overlay declares text/event-stream on the messages_post 200 response,
+# so the generator emits an OkStream variant alongside Ok(Message).
+schema_extensions = ["sse-overlay.json"]
+
+[features]
+enable_async_client = false
+
+[server]
+framework = "axum"
+operations = ["messages_post"]

examples/server-anthropic-messages/openapi-to-rust.toml

@@ -0,0 +1,147 @@
+//! Example: host a perfect-replica of Anthropic's `POST /v1/messages`.
+//!
+//! Exercises both branches of the typed response enum:
+//!   - `body.stream == Some(true)`  → `OkStream(Sse<...>)`
+//!   - otherwise                    → `Ok(Message)` (single JSON body)
+//!
+//! NOTE: Anthropic's published spec declares only `application/json`
+//! on the 200 response. This example pulls in a small overlay
+//! (`sse-overlay.json`) via the generator's `schema_extensions`
+//! mechanism, which declares `text/event-stream` on the 200 so the
+//! generated trait gets the `OkStream` variant.
+//!
+//! Run:
+//!   1. `cargo run -p openapi-to-rust -- generate \
+//!         --config examples/server-anthropic-messages/openapi-to-rust.toml`
+//!   2. `cargo run --manifest-path examples/server-anthropic-messages/Cargo.toml`
+//!   3. Unary:
+//!      `curl -s http://127.0.0.1:3001/v1/messages \
+//!         -H 'content-type: application/json' \
+//!         -d '{"model":"claude-x","max_tokens":50,
+//!              "messages":[{"role":"user","content":"hi"}]}'`
+//!   4. SSE:
+//!      `curl -N -s http://127.0.0.1:3001/v1/messages \
+//!         -H 'content-type: application/json' \
+//!         -d '{"model":"claude-x","max_tokens":50,"stream":true,
+//!              "messages":[{"role":"user","content":"hi"}]}'`
+
+pub mod gen;
+
+use axum::response::sse::{Event, KeepAlive, Sse};
+use futures_util::stream;
+use gen::CreateMessageParams;
+use gen::server::{MessagesPostResponse, ServerApi, ServerEventStream, server_api_router};
+use std::convert::Infallible;
+use std::time::Duration;
+
+#[derive(Clone)]
+struct AppState;
+
+#[axum::async_trait]
+impl ServerApi for AppState {
+    async fn messages_post(&self, body: CreateMessageParams) -> MessagesPostResponse {
+        if body.stream == Some(true) {
+            messages_streaming()
+        } else {
+            messages_unary()
+        }
+    }
+}
+
+fn messages_unary() -> MessagesPostResponse {
+    let msg = gen::Message {
+        container: None,
+        content: vec![gen::ContentBlock::TextBlock(gen::ResponseTextBlock {
+            citations: None,
+            text: "hello (unary)".into(),
+        })],
+        id: "msg_demo".into(),
+        model: gen::Model::Custom("claude-demo".into()),
+        role: gen::MessageRole::Assistant,
+        stop_details: None,
+        stop_reason: None,
+        stop_sequence: None,
+        r#type: gen::MessageType::Message,
+        usage: gen::Usage {
+            cache_creation: None,
+            cache_creation_input_tokens: None,
+            cache_read_input_tokens: None,
+            inference_geo: None,
+            input_tokens: 0,
+            output_tokens: 0,
+            server_tool_use: None,
+            service_tier: None,
+        },
+    };
+    MessagesPostResponse::Ok(msg)
+}
+
+fn messages_streaming() -> MessagesPostResponse {
+    // The real Anthropic stream emits message_start →
+    // content_block_start → content_block_delta* → content_block_stop
+    // → message_delta → message_stop. The example fires a short
+    // subset; production code mirrors the full sequence from the
+    // upstream model.
+    let events = stream::iter(vec![
+        sse_event("message_start", r#"{"type":"message_start","message":{"id":"msg_demo"}}"#),
+        sse_event(
+            "content_block_start",
+            r#"{"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}"#,
+        ),
+        sse_event(
+            "content_block_delta",
+            r#"{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"hello "}}"#,
+        ),
+        sse_event(
+            "content_block_delta",
+            r#"{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"world"}}"#,
+        ),
+        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))),
+    )
+}
+
+fn sse_event(name: &str, data: &str) -> Result<Event, Infallible> {
+    Ok(Event::default().event(name).data(data))
+}
+
+#[tokio::main]
+async fn main() {
+    let app = server_api_router(AppState);
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:3001").await.unwrap();
+    println!("listening on http://{}", listener.local_addr().unwrap());
+    axum::serve(listener, app).await.unwrap();
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn make_body(stream: Option<bool>) -> CreateMessageParams {
+        let mut json = serde_json::json!({
+            "model": "claude-x",
+            "max_tokens": 50,
+            "messages": [{"role": "user", "content": "hi"}],
+        });
+        if let Some(s) = stream {
+            json["stream"] = serde_json::Value::Bool(s);
+        }
+        serde_json::from_value(json).expect("minimal CreateMessageParams must deserialize")
+    }
+
+    #[tokio::test]
+    async fn unary_path_returns_ok_variant() {
+        let r = AppState.messages_post(make_body(None)).await;
+        assert!(matches!(r, MessagesPostResponse::Ok(_)));
+    }
+
+    #[tokio::test]
+    async fn stream_path_returns_ok_stream_variant() {
+        let r = AppState.messages_post(make_body(Some(true))).await;
+        assert!(matches!(r, MessagesPostResponse::OkStream(_)));
+    }
+}

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

@@ -0,0 +1,21 @@
+{
+  "_comment": "Schema extension overlay. Anthropic's published spec declares only application/json on POST /v1/messages 200, but the real API streams via text/event-stream when stream:true is in the request body. This overlay closes that gap so the generator emits an OkStream variant. Tracked as openapi-generator-in6.",
+  "paths": {
+    "/v1/messages": {
+      "post": {
+        "responses": {
+          "200": {
+            "content": {
+              "text/event-stream": {
+                "schema": {
+                  "type": "object",
+                  "description": "SSE event payload — opaque to the schema since the streaming protocol carries multiple event types."
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

examples/server-anthropic-messages/sse-overlay.json

@@ -0,0 +1,3 @@
+target/
+Cargo.lock
+src/gen/

examples/server-openai-responses/.gitignore

@@ -0,0 +1,22 @@
+[package]
+name = "server-openai-responses"
+version = "0.0.0"
+edition = "2021"
+publish = false
+
+[dependencies]
+axum = "0.7"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tokio = { version = "1", features = ["full"] }
+futures-core = "0.3"
+futures-util = "0.3"
+
+# Crates referenced by the generated types (see src/gen/REQUIRED_DEPS.toml
+# after running `openapi-to-rust generate`). For the OpenAI Responses
+# spec this is the union currently observed; if you add operations
+# that pull more types in, generate will surface the new deps in
+# stderr.
+bytes = { version = "1", features = ["serde"] }
+url = { version = "2", features = ["serde"] }
+chrono = { version = "0.4", features = ["serde"] }

examples/server-openai-responses/Cargo.toml

@@ -0,0 +1,24 @@
+# server-openai-responses
+
+End-to-end demo of the server codegen: scaffold `POST /v1/responses`
+from the OpenAI spec, implement the trait, serve it via axum.
+
+```bash
+# From repo root:
+cargo run -p openapi-to-rust -- generate \
+  --config examples/server-openai-responses/openapi-to-rust.toml
+
+cargo run --manifest-path examples/server-openai-responses/Cargo.toml
+
+# In another shell:
+curl -N -s http://127.0.0.1:3000/responses \
+  -H 'content-type: application/json' \
+  -d '{"model":"gpt-x","input":"hi","stream":true}'
+```
+
+The stub handler streams four canned SSE events. A real handler swaps
+the `stream::iter(...)` for a stream piped out of your model server.
+
+The integration test in `tests/server_examples_test.rs` runs both
+steps (generate + build) and is the canonical guarantee the example
+keeps working.