Parameters as struct implementing IntoParams for warp (and other frameworks)

Cargo.toml

@@ -38,8 +38,8 @@ serde_yaml = { version = "0.8", optional = true }
 utoipa-gen = { version = "1.1.0", path = "./utoipa-gen" }
 
 [dev-dependencies]
-assert-json-diff = "2"
 actix-web = { version = "4" }
+assert-json-diff = "2"
 paste = "1"
 chrono = { version  = "0.4", features = ["serde"] }
 rust_decimal = "1"

examples/todo-warp/src/main.rs

@@ -63,7 +63,9 @@ async fn serve_swagger(
     config: Arc<Config<'static>>,
 ) -> Result<Box<dyn Reply + 'static>, Rejection> {
     if full_path.as_str() == "/swagger-ui" {
-        return Ok(Box::new(warp::redirect::found(Uri::from_static("/swagger-ui/"))));
+        return Ok(Box::new(warp::redirect::found(Uri::from_static(
+            "/swagger-ui/",
+        ))));
     }
 
     let path = tail.as_str();
@@ -94,7 +96,7 @@ mod todo {
     };
 
     use serde::{Deserialize, Serialize};
-    use utoipa::Component;
+    use utoipa::{Component, IntoParams};
     use warp::{hyper::StatusCode, Filter, Reply};
 
     pub type Store = Arc<Mutex<Vec<Todo>>>;
@@ -110,13 +112,22 @@ mod todo {
         value: String,
     }
 
+    #[derive(Debug, Deserialize, IntoParams)]
+    #[into_params(parameter_in = Query)]
+    pub struct ListQueryParams {
+        /// Filters the returned `Todo` items according to whether they contain the specified string.
+        #[param(style = Form, example = json!("task"))]
+        contains: Option<String>,
+    }
+
     pub fn handlers() -> impl Filter<Extract = impl warp::Reply, Error = warp::Rejection> + Clone {
         let store = Store::default();
 
         let list = warp::path("todo")
             .and(warp::get())
             .and(warp::path::end())
             .and(with_store(store.clone()))
+            .and(warp::query::<ListQueryParams>())
             .and_then(list_todos);
 
         let create = warp::path("todo")
@@ -146,14 +157,28 @@ mod todo {
     #[utoipa::path(
         get,
         path = "/todo",
+        params(ListQueryParams),
         responses(
             (status = 200, description = "List todos successfully", body = [Todo])
         )
     )]
-    pub async fn list_todos(store: Store) -> Result<impl Reply, Infallible> {
+    pub async fn list_todos(
+        store: Store,
+        query: ListQueryParams,
+    ) -> Result<impl Reply, Infallible> {
         let todos = store.lock().unwrap();
 
-        Ok(warp::reply::json(&todos.clone()))
+        let todos: Vec<Todo> = if let Some(contains) = query.contains {
+            todos
+                .iter()
+                .filter(|todo| todo.value.contains(&contains))
+                .cloned()
+                .collect()
+        } else {
+            todos.clone()
+        };
+
+        Ok(warp::reply::json(&todos))
     }
 
     /// Create new todo item.

src/lib.rs

@@ -123,7 +123,7 @@
 //!             (status = 404, description = "Pet was not found")
 //!         ),
 //!         params(
-//!             ("id" = u64, path, description = "Pet database id to get Pet for"),
+//!             ("id" = u64, Path, description = "Pet database id to get Pet for"),
 //!         )
 //!     )]
 //!     async fn get_pet_by_id(pet_id: u64) -> Pet {
@@ -159,7 +159,7 @@
 //! #             (status = 404, description = "Pet was not found")
 //! #         ),
 //! #         params(
-//! #             ("id" = u64, path, description = "Pet database id to get Pet for"),
+//! #             ("id" = u64, Path, description = "Pet database id to get Pet for"),
 //! #         )
 //! #     )]
 //! #     async fn get_pet_by_id(pet_id: u64) -> Pet {
@@ -344,7 +344,7 @@ pub trait Component {
 ///         (status = 404, description = "Pet was not found")
 ///     ),
 ///     params(
-///         ("id" = u64, path, description = "Pet database id to get Pet for"),
+///         ("id" = u64, Path, description = "Pet database id to get Pet for"),
 ///     )
 /// )]
 /// async fn get_pet_by_id(pet_id: u64) -> Pet {
@@ -472,7 +472,7 @@ pub trait Modify {
     fn modify(&self, openapi: &mut openapi::OpenApi);
 }
 
-/// Trait used to convert implementing type to OpenAPI parameters for **actix-web** framework.
+/// Trait used to convert implementing type to OpenAPI parameters.
 ///
 /// This trait is [derivable][derive] for structs which are used to describe `path` or `query` parameters.
 /// For more details of `#[derive(IntoParams)]` refer to [derive documentation][derive].
@@ -482,7 +482,7 @@ pub trait Modify {
 /// Derive [`IntoParams`] implementation. This example will fail to compile because [`IntoParams`] cannot
 /// be used alone and it need to be used together with endpoint using the params as well. See
 /// [derive documentation][derive] for more details.
-/// ```compile_fail
+/// ```
 /// use utoipa::{IntoParams};
 ///
 /// #[derive(IntoParams)]
@@ -503,12 +503,14 @@ pub trait Modify {
 /// #    name: String,
 /// # }
 /// impl utoipa::IntoParams for PetParams {
-///     fn into_params() -> Vec<utoipa::openapi::path::Parameter> {
+///     fn into_params(
+///         parameter_in_provider: impl Fn() -> Option<utoipa::openapi::path::ParameterIn>
+///     ) -> Vec<utoipa::openapi::path::Parameter> {
 ///         vec![
 ///             utoipa::openapi::path::ParameterBuilder::new()
 ///                 .name("id")
 ///                 .required(utoipa::openapi::Required::True)
-///                 .parameter_in(utoipa::openapi::path::ParameterIn::Path)
+///                 .parameter_in(parameter_in_provider().unwrap_or_default())
 ///                 .description(Some("Id of pet"))
 ///                 .schema(Some(
 ///                     utoipa::openapi::PropertyBuilder::new()
@@ -519,7 +521,7 @@ pub trait Modify {
 ///             utoipa::openapi::path::ParameterBuilder::new()
 ///                 .name("name")
 ///                 .required(utoipa::openapi::Required::True)
-///                 .parameter_in(utoipa::openapi::path::ParameterIn::Path)
+///                 .parameter_in(parameter_in_provider().unwrap_or_default())
 ///                 .description(Some("Name of pet"))
 ///                 .schema(Some(
 ///                     utoipa::openapi::PropertyBuilder::new()
@@ -531,7 +533,6 @@ pub trait Modify {
 /// }
 /// ```
 /// [derive]: derive.IntoParams.html
-#[cfg(feature = "actix_extras")]
 pub trait IntoParams {
     /// Provide [`Vec`] of [`openapi::path::Parameter`]s to caller. The result is used in `utoipa-gen` library to
     /// provide OpenAPI parameter information for the endpoint using the parameters.

tests/path_derive.rs

@@ -1,5 +1,8 @@
 #![cfg(feature = "serde_json")]
+use assert_json_diff::assert_json_eq;
 use paste::paste;
+use serde_json::{json, Value};
+use utoipa::IntoParams;
 
 mod common;
 
@@ -157,7 +160,7 @@ fn derive_path_with_defaults_success() {
     ),
     params(
         ("id" = u64, description = "Foo database id"),
-        ("since" = Option<String>, query, description = "Datetime since foo is updated")
+        ("since" = Option<String>, Query, description = "Datetime since foo is updated")
     )
 )]
 #[allow(unused)]
@@ -231,6 +234,91 @@ fn derive_path_with_security_requirements() {
     }
 }
 
+#[test]
+fn derive_path_params_intoparams() {
+    #[derive(serde::Deserialize, IntoParams)]
+    #[into_params(style = Form, parameter_in = Query)]
+    struct MyParams {
+        /// Foo database id.
+        #[param(example = 1)]
+        #[allow(unused)]
+        id: u64,
+        /// Datetime since foo is updated.
+        #[param(example = "2020-04-12T10:23:00Z")]
+        #[allow(unused)]
+        since: Option<String>,
+    }
+
+    #[utoipa::path(
+        get,
+        path = "/list/{id}",
+        responses(
+            (status = 200, description = "success response")
+        ),
+        params(
+            MyParams,
+            ("id" = i64, Path, description = "Id of some items to list")
+        )
+    )]
+    #[allow(unused)]
+    fn list(id: i64, params: MyParams) -> String {
+        "".to_string()
+    }
+
+    use utoipa::OpenApi;
+    #[derive(OpenApi, Default)]
+    #[openapi(handlers(list))]
+    struct ApiDoc;
+
+    let operation: Value = test_api_fn_doc! {
+        list,
+        operation: get,
+        path: "/list/{id}"
+    };
+
+    let parameters = operation.get("parameters").unwrap();
+
+    assert_json_eq!(
+        parameters,
+        json!([
+            {
+                "description": "Foo database id.",
+                "example": 1,
+                "in": "query",
+                "name": "id",
+                "required": true,
+                "schema": {
+                    "format": "int64",
+                    "type": "integer"
+                },
+                "style": "form"
+            },
+            {
+                "description": "Datetime since foo is updated.",
+                "example": "2020-04-12T10:23:00Z",
+                "in": "query",
+                "name": "since",
+                "required": false,
+                "schema": {
+                    "type": "string"
+                },
+                "style": "form"
+            },
+            {
+                "deprecated": false,
+                "description": "Id of some items to list",
+                "in": "path",
+                "name": "id",
+                "required": true,
+                "schema": {
+                    "format": "int64",
+                    "type": "integer"
+                }
+            }
+        ])
+    )
+}
+
 #[cfg(feature = "uuid")]
 #[test]
 fn derive_path_with_uuid() {

tests/path_parameter_derive_test.rs

@@ -16,7 +16,7 @@ mod derive_params_all_options {
             (status = 200, description = "success"),
         ),
         params(
-            ("id" = i32, path, deprecated, description = "Search foos by ids"),
+            ("id" = i32, Path, deprecated, description = "Search foos by ids"),
         )
     )]
     #[allow(unused)]
@@ -148,11 +148,11 @@ mod mod_derive_parameters_all_types {
             (status = 200, description = "success"),
         ),
         params(
-            ("id" = i32, path, description = "Foo id"),
-            ("since" = String, deprecated, query, description = "Datetime since"),
-            ("numbers" = Option<[u64]>, query, description = "Foo numbers list"),
-            ("token" = String, header, deprecated, description = "Token of foo"),
-            ("cookieval" = String, cookie, deprecated, description = "Foo cookie"),
+            ("id" = i32, Path, description = "Foo id"),
+            ("since" = String, deprecated, Query, description = "Datetime since"),
+            ("numbers" = Option<[u64]>, Query, description = "Foo numbers list"),
+            ("token" = String, Header, deprecated, description = "Token of foo"),
+            ("cookieval" = String, Cookie, deprecated, description = "Foo cookie"),
         )
     )]
     #[allow(unused)]
@@ -224,7 +224,7 @@ mod derive_params_without_args {
             (status = 200, description = "success"),
         ),
         params(
-            ("id" = i32, path, description = "Foo id"),
+            ("id" = i32, Path, description = "Foo id"),
         )
     )]
     #[allow(unused)]
@@ -263,7 +263,7 @@ fn derive_params_with_params_ext() {
             (status = 200, description = "success"),
         ),
         params(
-            ("value" = Option<[String]>, query, description = "Foo value description", style = Form, allow_reserved, deprecated, explode)
+            ("value" = Option<[String]>, Query, description = "Foo value description", style = Form, allow_reserved, deprecated, explode)
         )
     )]
     #[allow(unused)]