Add TypedPath and ApiError derive macros with typed routing

Introduces the TypedPath trait and derive macro for type-safe, declarative route definitions and URL generation. Adds a Typed extractor for ergonomic path parameter extraction. Implements the ApiError derive macro for declarative error handling. Refactors test client into rustapi-testing crate, updates re-exports, and adds integration and derive macro tests. Updates documentation and examples to showcase new features.

Author: Tuntii

Cargo.lock

@@ -211,8 +211,31 @@ rustapi-rs = { version = "0.1.9", features = ["jwt", "cors", "toon", "ws", "view
 | `audit` | GDPR/SOC2 audit logging |
 | `full` | All features enabled |
 
+
+### ✨ New Ergonomic Features
+
+**Declarative Error Handling:**
+```rust
+#[derive(ApiError)]
+pub enum UserError {
+    #[error(status = 404, message = "User not found")]
+    NotFound(i32),
+    #[error(status = 400, code = "validation_error")]
+    InvalidInput(String),
+}
+```
+
+**Fluent Testing:**
+```rust
+let client = TestClient::new(app);
+client.get("/users").await
+    .assert_status(200)
+    .assert_json(&expected_users);
+```
+
 ---
 
+
 ## 📂 Examples
 
 All examples are production-ready and follow best practices.

README.md

@@ -390,6 +390,11 @@ impl RustApi {
         self
     }
 
+    /// Add a typed route
+    pub fn typed<P: crate::typed_path::TypedPath>(self, method_router: MethodRouter) -> Self {
+        self.route(P::PATH, method_router)
+    }
+
     /// Mount a handler (convenience method)
     ///
     /// Alias for `.route(path, method_router)` for a single handler.

crates/rustapi-core/src/app.rs

@@ -340,6 +340,50 @@ impl<T> Deref for Path<T> {
     }
 }
 
+/// Typed path extractor
+///
+/// Extracts path parameters and deserializes them into a struct implementing `Deserialize`.
+/// This is similar to `Path<T>`, but supports complex structs that can be deserialized
+/// from a map of parameter names to values (e.g. via `serde_json`).
+///
+/// # Example
+///
+/// ```rust,ignore
+/// #[derive(Deserialize)]
+/// struct UserParams {
+///     id: u64,
+///     category: String,
+/// }
+///
+/// async fn get_user(Typed(params): Typed<UserParams>) -> impl IntoResponse {
+///     // params.id, params.category
+/// }
+/// ```
+#[derive(Debug, Clone)]
+pub struct Typed<T>(pub T);
+
+impl<T: DeserializeOwned + Send> FromRequestParts for Typed<T> {
+    fn from_request_parts(req: &Request) -> Result<Self> {
+        let params = req.path_params();
+        let mut map = serde_json::Map::new();
+        for (k, v) in params.iter() {
+            map.insert(k.to_string(), serde_json::Value::String(v.to_string()));
+        }
+        let value = serde_json::Value::Object(map);
+        let parsed: T = serde_json::from_value(value)
+            .map_err(|e| ApiError::bad_request(format!("Invalid path parameters: {}", e)))?;
+        Ok(Typed(parsed))
+    }
+}
+
+impl<T> Deref for Typed<T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
 /// State extractor
 ///
 /// Extracts shared application state.
@@ -851,6 +895,13 @@ impl<T> OperationModifier for Path<T> {
     }
 }
 
+// Typed - Same as Path, parameters are documented by route pattern
+impl<T> OperationModifier for Typed<T> {
+    fn update_operation(_op: &mut Operation) {
+        // No-op, managed by route registration
+    }
+}
+
 // Query - Extracts query params using IntoParams
 impl<T: IntoParams> OperationModifier for Query<T> {
     fn update_operation(op: &mut Operation) {

crates/rustapi-core/src/extract.rs

@@ -70,10 +70,9 @@ mod server;
 pub mod sse;
 pub mod static_files;
 pub mod stream;
+pub mod typed_path;
 #[macro_use]
 mod tracing_macros;
-#[cfg(any(test, feature = "test-utils"))]
-mod test_client;
 
 /// Private module for macro internals - DO NOT USE DIRECTLY
 ///
@@ -94,25 +93,25 @@ pub use error::{get_environment, ApiError, Environment, FieldError, Result};
 pub use extract::Cookies;
 pub use extract::{
     Body, BodyStream, ClientIp, Extension, FromRequest, FromRequestParts, HeaderValue, Headers,
-    Json, Path, Query, State, ValidatedJson,
+    Json, Path, Query, State, Typed, ValidatedJson,
 };
 pub use handler::{
     delete_route, get_route, patch_route, post_route, put_route, Handler, HandlerService, Route,
     RouteHandler,
 };
 pub use health::{HealthCheck, HealthCheckBuilder, HealthCheckResult, HealthStatus};
+pub use http::StatusCode;
 pub use interceptor::{InterceptorChain, RequestInterceptor, ResponseInterceptor};
 #[cfg(feature = "compression")]
 pub use middleware::CompressionLayer;
 pub use middleware::{BodyLimitLayer, RequestId, RequestIdLayer, TracingLayer, DEFAULT_BODY_LIMIT};
 #[cfg(feature = "metrics")]
 pub use middleware::{MetricsLayer, MetricsResponse};
 pub use multipart::{Multipart, MultipartConfig, MultipartField, UploadedFile};
-pub use request::Request;
+pub use request::{BodyVariant, Request};
 pub use response::{Created, Html, IntoResponse, NoContent, Redirect, Response, WithStatus};
-pub use router::{delete, get, patch, post, put, MethodRouter, Router};
+pub use router::{delete, get, patch, post, put, MethodRouter, RouteMatch, Router};
 pub use sse::{sse_response, KeepAlive, Sse, SseEvent};
 pub use static_files::{serve_dir, StaticFile, StaticFileConfig};
 pub use stream::{StreamBody, StreamingBody, StreamingConfig};
-#[cfg(any(test, feature = "test-utils"))]
-pub use test_client::{TestClient, TestRequest, TestResponse};
+pub use typed_path::TypedPath;

crates/rustapi-core/src/lib.rs

@@ -47,7 +47,7 @@ use hyper::body::Incoming;
 use std::sync::Arc;
 
 /// Internal representation of the request body state
-pub(crate) enum BodyVariant {
+pub enum BodyVariant {
     Buffered(Bytes),
     Streaming(Incoming),
     Consumed,
@@ -65,7 +65,7 @@ pub struct Request {
 
 impl Request {
     /// Create a new request from parts
-    pub(crate) fn new(
+    pub fn new(
         parts: Parts,
         body: BodyVariant,
         state: Arc<Extensions>,

crates/rustapi-core/src/request.rs

@@ -43,6 +43,7 @@
 
 use crate::handler::{into_boxed_handler, BoxedHandler, Handler};
 use crate::path_params::PathParams;
+use crate::typed_path::TypedPath;
 use http::{Extensions, Method};
 use matchit::Router as MatchitRouter;
 use rustapi_openapi::Operation;
@@ -331,6 +332,11 @@ impl Router {
         }
     }
 
+    /// Add a typed route using a TypedPath
+    pub fn typed<P: TypedPath>(self, method_router: MethodRouter) -> Self {
+        self.route(P::PATH, method_router)
+    }
+
     /// Add a route
     pub fn route(mut self, path: &str, method_router: MethodRouter) -> Self {
         // Convert {param} style to :param for matchit
@@ -573,7 +579,7 @@ impl Router {
     }
 
     /// Match a request and return the handler + params
-    pub(crate) fn match_route(&self, path: &str, method: &Method) -> RouteMatch<'_> {
+    pub fn match_route(&self, path: &str, method: &Method) -> RouteMatch<'_> {
         match self.inner.at(path) {
             Ok(matched) => {
                 let method_router = matched.value;
@@ -598,7 +604,7 @@ impl Router {
     }
 
     /// Get shared state
-    pub(crate) fn state_ref(&self) -> Arc<Extensions> {
+    pub fn state_ref(&self) -> Arc<Extensions> {
         self.state.clone()
     }
 
@@ -620,7 +626,7 @@ impl Default for Router {
 }
 
 /// Result of route matching
-pub(crate) enum RouteMatch<'a> {
+pub enum RouteMatch<'a> {
     Found {
         handler: &'a BoxedHandler,
         params: PathParams,

crates/rustapi-core/src/router.rs

@@ -0,0 +1,13 @@
+use serde::{de::DeserializeOwned, Serialize};
+
+/// Trait for defining typed paths
+///
+/// This trait allows structs to define their own path pattern and URL generation logic.
+/// It is usually implemented via `#[derive(TypedPath)]`.
+pub trait TypedPath: Serialize + DeserializeOwned + Send + Sync + 'static {
+    /// The URL path pattern (e.g., "/users/{id}")
+    const PATH: &'static str;
+
+    /// Convert the struct fields to a path string
+    fn to_uri(&self) -> String;
+}

crates/rustapi-core/src/typed_path.rs

@@ -195,7 +195,13 @@ impl MiddlewareLayer for CorsLayer {
     ) -> Pin<Box<dyn Future<Output = Response> + Send + 'static>> {
         let origins = self.origins.clone();
         let methods = self.methods_header_value();
-        let allow_headers = if self.headers.len() == 1 && self.headers.first().map(|value| value == "*").unwrap_or(false) {
+        let allow_headers = if self.headers.len() == 1
+            && self
+                .headers
+                .first()
+                .map(|value| value == "*")
+                .unwrap_or(false)
+        {
             req.headers()
                 .get(header::ACCESS_CONTROL_REQUEST_HEADERS)
                 .and_then(|value| value.to_str().ok())