feat(axum): typed path support (#214)

Author: dzmitry-lahoda

crates/aide-macros/Cargo.toml

@@ -13,3 +13,7 @@ proc-macro = true
 darling = "0.20.0"
 quote = "1.0.21"
 syn = "2.0.15"
+proc-macro2 = "1.0"
+
+[features]
+axum-extra-typed-routing = []

crates/aide-macros/src/lib.rs

@@ -166,3 +166,26 @@ pub fn derive_operation_io(ts: TokenStream) -> TokenStream {
 
     ts.into()
 }
+
+#[cfg(feature = "axum-extra-typed-routing")]
+/// Example usage:
+/// ```ignore
+/// #[aide::axum_typed_path]
+/// #[typed_path("/foo/bar")]
+/// struct FooBar;
+/// ```
+#[proc_macro_attribute] // functions tagged with `#[proc_macro_attribute]` must currently reside in the root of the crate
+pub fn axum_typed_path(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    let input = proc_macro2::TokenStream::from(item);
+    quote! {
+        #[derive(
+            ::axum_extra::routing::TypedPath,
+            ::aide_macros::OperationIo,
+            ::schemars::JsonSchema,
+            ::serde::Deserialize,
+        )]
+        #[aide(input_with = "aide::axum::routing::typed::TypedPath<Self>")]
+        #input
+    }
+    .into()
+}

crates/aide/CHANGELOG.md

@@ -1,5 +1,6 @@
 # Changelog
 ## Latest
+- **added:** Basic `axum` `TypedPath` support and `TypedPath<T>` description from `T` doc comment([#212])
 - **added:** Add methods for attaching documentation to existing routes ([#203])
 - **fixed:** Fix `route_with_tsr` incorrect handling ([#203])
 

crates/aide/Cargo.toml

@@ -23,7 +23,7 @@ http = { version = "1.0.0", optional = true }
 serde_qs = { version = "0.14", optional = true }
 
 axum = { version = "0.8.1", optional = true, default-features = false }
-axum-extra = { version = "0.10.0", optional = true }
+axum-extra = { version = "0.10", optional = true }
 tower-layer = { version = "0.3", optional = true }
 tower-service = { version = "0.3", optional = true }
 cfg-if = "1.0.0"
@@ -53,6 +53,7 @@ axum-extra-form = ["axum-extra", "axum-extra/form"]
 axum-extra-headers = ["axum-extra/typed-header"]
 axum-extra-query = ["axum-extra", "axum-extra/query"]
 axum-extra-json-deserializer = ["axum-extra", "axum-extra/json-deserializer"]
+axum-extra-typed-routing = ["axum-extra", "axum-extra/typed-routing"]
 
 [dev-dependencies]
 tokio = { version = "1.21.0", features = ["macros", "rt-multi-thread"] }

crates/aide/src/axum/routing.rs crates/aide/src/axum/routing/mod.rscrates/aide/src/axum/routing.rs renamed to crates/aide/src/axum/routing/mod.rs

@@ -1,5 +1,7 @@
 //! Method routing that closely mimics [`axum::routing`] while extending
 //! it with API documentation-specific features..
+#[cfg(feature = "axum-extra-typed-routing")]
+pub mod typed;
 
 use std::{convert::Infallible, mem};
 

crates/aide/src/axum/routing/typed.rs

@@ -0,0 +1,182 @@
+//! Typed routing for Axum.
+
+use axum::extract::rejection::PathRejection;
+use axum_extra::routing::SecondElementIs;
+use http::request::Parts;
+use schemars::JsonSchema;
+use serde::de::DeserializeOwned;
+
+use super::*;
+use crate::operation::{add_parameters, parameters_from_schema, OperationHandler, ParamLocation};
+
+impl<S> crate::axum::ApiRouter<S>
+where
+    S: Clone + Send + Sync + 'static,
+{
+    /// Add a typed `GET` route to the router.
+    ///
+    /// The path will be inferred from the first argument to the handler function which must
+    /// implement [`TypedPath`].
+    pub fn typed_get<H, I, O, T, P>(self, handler: H) -> Self
+    where
+        H: axum::handler::Handler<T, S> + OperationHandler<I, O>,
+        T: SecondElementIs<P> + 'static,
+        I: OperationInput,
+        O: OperationOutput,
+        P: axum_extra::routing::TypedPath + schemars::JsonSchema + OperationInput,
+    {
+        self.api_route(P::PATH, crate::axum::routing::get(handler))
+    }
+
+    /// Add a typed `DELETE` route to the router.
+    ///
+    /// The path will be inferred from the first argument to the handler function which must
+    /// implement [`TypedPath`].
+    pub fn typed_delete<H, I, O, T, P>(self, handler: H) -> Self
+    where
+        H: axum::handler::Handler<T, S> + OperationHandler<I, O>,
+        T: SecondElementIs<P> + 'static,
+        I: OperationInput,
+        O: OperationOutput,
+        P: axum_extra::routing::TypedPath + schemars::JsonSchema + OperationInput,
+    {
+        self.api_route(P::PATH, crate::axum::routing::delete(handler))
+    }
+
+    /// Add a typed `HEAD` route to the router.
+    ///
+    /// The path will be inferred from the first argument to the handler function which must
+    /// implement [`TypedPath`].
+    pub fn typed_head<H, I, O, T, P>(self, handler: H) -> Self
+    where
+        H: axum::handler::Handler<T, S> + OperationHandler<I, O>,
+        T: SecondElementIs<P> + 'static,
+        I: OperationInput,
+        O: OperationOutput,
+        P: axum_extra::routing::TypedPath + schemars::JsonSchema + OperationInput,
+    {
+        self.api_route(P::PATH, crate::axum::routing::head(handler))
+    }
+
+    /// Add a typed `OPTIONS` route to the router.
+    ///
+    /// The path will be inferred from the first argument to the handler function which must
+    /// implement [`TypedPath`].
+    pub fn typed_options<H, I, O, T, P>(self, handler: H) -> Self
+    where
+        H: axum::handler::Handler<T, S> + OperationHandler<I, O>,
+        T: SecondElementIs<P> + 'static,
+        I: OperationInput,
+        O: OperationOutput,
+        P: axum_extra::routing::TypedPath + schemars::JsonSchema + OperationInput,
+    {
+        self.api_route(P::PATH, crate::axum::routing::options(handler))
+    }
+
+    /// Add a typed `PATCH` route to the router.
+    ///
+    /// The path will be inferred from the first argument to the handler function which must
+    /// implement [`TypedPath`].
+    pub fn typed_patch<H, I, O, T, P>(self, handler: H) -> Self
+    where
+        H: axum::handler::Handler<T, S> + OperationHandler<I, O>,
+        T: SecondElementIs<P> + 'static,
+        I: OperationInput,
+        O: OperationOutput,
+        P: axum_extra::routing::TypedPath + schemars::JsonSchema + OperationInput,
+    {
+        self.api_route(P::PATH, crate::axum::routing::patch(handler))
+    }
+
+    /// Add a typed `POST` route to the router.
+    ///
+    /// The path will be inferred from the first argument to the handler function which must
+    /// implement [`TypedPath`].
+    pub fn typed_post<H, I, O, T, P>(self, handler: H) -> Self
+    where
+        H: axum::handler::Handler<T, S> + OperationHandler<I, O>,
+        T: SecondElementIs<P> + 'static,
+        I: OperationInput,
+        O: OperationOutput,
+        P: axum_extra::routing::TypedPath + schemars::JsonSchema + OperationInput,
+    {
+        self.api_route(P::PATH, crate::axum::routing::post(handler))
+    }
+
+    /// Add a typed `PUT` route to the router.
+    ///
+    /// The path will be inferred from the first argument to the handler function which must
+    /// implement [`TypedPath`].
+    pub fn typed_put<H, I, O, T, P>(self, handler: H) -> Self
+    where
+        H: axum::handler::Handler<T, S> + OperationHandler<I, O>,
+        T: SecondElementIs<P> + 'static,
+        I: OperationInput,
+        O: OperationOutput,
+        P: axum_extra::routing::TypedPath + schemars::JsonSchema + OperationInput,
+    {
+        self.api_route(P::PATH, crate::axum::routing::put(handler))
+    }
+
+    /// Add a typed `TRACE` route to the router.
+    ///
+    /// The path will be inferred from the first argument to the handler function which must
+    /// implement [`TypedPath`].
+    pub fn typed_trace<H, I, O, T, P>(self, handler: H) -> Self
+    where
+        H: axum::handler::Handler<T, S> + OperationHandler<I, O>,
+        T: SecondElementIs<P> + 'static,
+        I: OperationInput,
+        O: OperationOutput,
+        P: axum_extra::routing::TypedPath + schemars::JsonSchema + OperationInput,
+    {
+        self.api_route(P::PATH, crate::axum::routing::trace(handler))
+    }
+}
+
+/// A wrapper around `axum_extra::routing::TypedPath` to implement `OperationInput`.
+/// Basically fix for Rust does not support `!Trait` and specialization on stable.
+#[derive(Debug)]
+pub struct TypedPath<T: axum_extra::routing::TypedPath + JsonSchema>(pub T);
+
+impl<T> OperationInput for TypedPath<T>
+where
+    T: axum_extra::routing::TypedPath + JsonSchema,
+{
+    fn operation_input(ctx: &mut crate::generate::GenContext, operation: &mut Operation) {
+        // `subschema_for` `description` is none, while `root_schema_for` is some
+        let schema = ctx.schema.root_schema_for::<T>().schema;
+        operation.description = schema.metadata.as_ref().and_then(|x| x.description.clone());
+        let params = parameters_from_schema(ctx, schema, ParamLocation::Path);
+        add_parameters(ctx, operation, params);
+    }
+}
+
+impl<T, S> axum::extract::FromRequestParts<S> for TypedPath<T>
+where
+    T: DeserializeOwned + Send + axum_extra::routing::TypedPath + JsonSchema,
+    S: Send + Sync,
+{
+    type Rejection = PathRejection;
+
+    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        let path = axum::extract::Path::<T>::from_request_parts(parts, state).await?;
+        Ok(Self(path.0))
+    }
+}
+
+impl<T, S> axum::extract::OptionalFromRequestParts<S> for TypedPath<T>
+where
+    T: DeserializeOwned + Send + 'static + axum_extra::routing::TypedPath + JsonSchema,
+    S: Send + Sync,
+{
+    type Rejection = PathRejection;
+
+    async fn from_request_parts(
+        parts: &mut Parts,
+        state: &S,
+    ) -> Result<Option<Self>, Self::Rejection> {
+        let path = axum::extract::Path::<T>::from_request_parts(parts, state).await?;
+        Ok(path.map(|x| Self(x.0)))
+    }
+}