spikard 0.3.5 → 0.5.0

data/vendor/crates/spikard-http/src/openapi/parameter_extraction.rs

@@ -1,190 +1,535 @@
-//! Parameter extraction from routes and schemas for OpenAPI generation
-
-use utoipa::openapi::RefOr;
-use utoipa::openapi::path::Parameter;
-use utoipa::openapi::path::{ParameterBuilder, ParameterIn};
-
-/// Extract parameters from JSON Schema parameter_schema
-pub fn extract_parameters_from_schema(
-    param_schema: &serde_json::Value,
-    route_path: &str,
-) -> Result<Vec<RefOr<Parameter>>, String> {
-    let mut parameters = Vec::new();
-
-    let path_params = extract_path_param_names(route_path);
-
-    let properties = param_schema
-        .get("properties")
-        .and_then(|p| p.as_object())
-        .ok_or_else(|| "Parameter schema missing 'properties' field".to_string())?;
-
-    let required = param_schema
-        .get("required")
-        .and_then(|r| r.as_array())
-        .map(|arr| arr.iter().filter_map(|v| v.as_str()).collect::<Vec<_>>())
-        .unwrap_or_default();
-
-    for (name, schema) in properties {
-        let is_required = required.contains(&name.as_str());
-        let param_in = if path_params.contains(&name.as_str()) {
-            ParameterIn::Path
-        } else {
-            ParameterIn::Query
-        };
-
-        let openapi_schema = crate::openapi::schema_conversion::json_value_to_schema(schema)?;
-
-        let is_path_param = matches!(param_in, ParameterIn::Path);
-
-        let param = ParameterBuilder::new()
-            .name(name)
-            .parameter_in(param_in)
-            .required(if is_path_param || is_required {
-                utoipa::openapi::Required::True
-            } else {
-                utoipa::openapi::Required::False
-            })
-            .schema(Some(openapi_schema))
-            .build();
-
-        parameters.push(RefOr::T(param));
-    }
-
-    Ok(parameters)
-}
-
-/// Extract path parameter names from route pattern (e.g., "/users/{id}" -> ["id"])
-pub fn extract_path_param_names(route: &str) -> Vec<&str> {
-    route
-        .split('/')
-        .filter_map(|segment| {
-            if segment.starts_with('{') && segment.ends_with('}') {
-                Some(&segment[1..segment.len() - 1])
-            } else {
-                None
-            }
-        })
-        .collect()
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use serde_json::json;
-
-    #[test]
-    fn test_extract_path_param_names() {
-        let names = extract_path_param_names("/users/{id}/posts/{post_id}");
-        assert_eq!(names, vec!["id", "post_id"]);
-
-        let names = extract_path_param_names("/users");
-        assert_eq!(names, Vec::<&str>::new());
-
-        let names = extract_path_param_names("/users/{user_id}");
-        assert_eq!(names, vec!["user_id"]);
-    }
-
-    #[test]
-    fn test_extract_parameters_from_schema_path_params() {
-        let param_schema = json!({
-            "type": "object",
-            "properties": {
-                "user_id": { "type": "integer" },
-                "post_id": { "type": "integer" }
-            },
-            "required": ["user_id", "post_id"]
-        });
-
-        let result = extract_parameters_from_schema(&param_schema, "/users/{user_id}/posts/{post_id}");
-        assert!(result.is_ok());
-
-        let params = result.unwrap();
-        assert_eq!(params.len(), 2);
-
-        for param in params {
-            if let RefOr::T(p) = param {
-                assert!(matches!(p.parameter_in, ParameterIn::Path));
-                assert!(matches!(p.required, utoipa::openapi::Required::True));
-            }
-        }
-    }
-
-    #[test]
-    fn test_extract_parameters_from_schema_query_params() {
-        let param_schema = json!({
-            "type": "object",
-            "properties": {
-                "page": { "type": "integer" },
-                "limit": { "type": "integer" },
-                "search": { "type": "string" }
-            },
-            "required": ["page"]
-        });
-
-        let result = extract_parameters_from_schema(&param_schema, "/users");
-        assert!(result.is_ok());
-
-        let params = result.unwrap();
-        assert_eq!(params.len(), 3);
-
-        for param in &params {
-            if let RefOr::T(p) = param {
-                assert!(matches!(p.parameter_in, ParameterIn::Query));
-            }
-        }
-
-        for param in params {
-            if let RefOr::T(p) = param {
-                if p.name == "page" {
-                    assert!(matches!(p.required, utoipa::openapi::Required::True));
-                } else {
-                    assert!(matches!(p.required, utoipa::openapi::Required::False));
-                }
-            }
-        }
-    }
-
-    #[test]
-    fn test_extract_parameters_from_schema_mixed() {
-        let param_schema = json!({
-            "type": "object",
-            "properties": {
-                "user_id": { "type": "integer" },
-                "page": { "type": "integer" },
-                "limit": { "type": "integer" }
-            },
-            "required": ["user_id"]
-        });
-
-        let result = extract_parameters_from_schema(&param_schema, "/users/{user_id}");
-        assert!(result.is_ok());
-
-        let params = result.unwrap();
-        assert_eq!(params.len(), 3);
-
-        for param in params {
-            if let RefOr::T(p) = param {
-                if p.name == "user_id" {
-                    assert!(matches!(p.parameter_in, ParameterIn::Path));
-                    assert!(matches!(p.required, utoipa::openapi::Required::True));
-                } else {
-                    assert!(matches!(p.parameter_in, ParameterIn::Query));
-                    assert!(matches!(p.required, utoipa::openapi::Required::False));
-                }
-            }
-        }
-    }
-
-    #[test]
-    fn test_extract_parameters_error_on_missing_properties() {
-        let param_schema = json!({
-            "type": "object"
-        });
-
-        let result = extract_parameters_from_schema(&param_schema, "/users");
-        assert!(result.is_err());
-        if let Err(err) = result {
-            assert!(err.contains("properties"));
-        }
-    }
-}
+//! Parameter extraction from routes and schemas for OpenAPI generation
+
+use utoipa::openapi::RefOr;
+use utoipa::openapi::path::Parameter;
+use utoipa::openapi::path::{ParameterBuilder, ParameterIn};
+
+/// Extract parameters from JSON Schema parameter_schema
+pub fn extract_parameters_from_schema(
+    param_schema: &serde_json::Value,
+    route_path: &str,
+) -> Result<Vec<RefOr<Parameter>>, String> {
+    let mut parameters = Vec::new();
+
+    let path_params = extract_path_param_names(route_path);
+
+    let properties = param_schema
+        .get("properties")
+        .and_then(|p| p.as_object())
+        .ok_or_else(|| "Parameter schema missing 'properties' field".to_string())?;
+
+    let required = param_schema
+        .get("required")
+        .and_then(|r| r.as_array())
+        .map(|arr| arr.iter().filter_map(|v| v.as_str()).collect::<Vec<_>>())
+        .unwrap_or_default();
+
+    for (name, schema) in properties {
+        let is_required = required.contains(&name.as_str());
+        let param_in = if path_params.contains(&name.as_str()) {
+            ParameterIn::Path
+        } else {
+            ParameterIn::Query
+        };
+
+        let openapi_schema = crate::openapi::schema_conversion::json_value_to_schema(schema)?;
+
+        let is_path_param = matches!(param_in, ParameterIn::Path);
+
+        let param = ParameterBuilder::new()
+            .name(name)
+            .parameter_in(param_in)
+            .required(if is_path_param || is_required {
+                utoipa::openapi::Required::True
+            } else {
+                utoipa::openapi::Required::False
+            })
+            .schema(Some(openapi_schema))
+            .build();
+
+        parameters.push(RefOr::T(param));
+    }
+
+    Ok(parameters)
+}
+
+/// Extract path parameter names from route pattern (e.g., "/users/{id}" -> ["id"])
+pub fn extract_path_param_names(route: &str) -> Vec<&str> {
+    route
+        .split('/')
+        .filter_map(|segment| {
+            if segment.starts_with('{') && segment.ends_with('}') {
+                Some(&segment[1..segment.len() - 1])
+            } else {
+                None
+            }
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn test_extract_path_param_names() {
+        let names = extract_path_param_names("/users/{id}/posts/{post_id}");
+        assert_eq!(names, vec!["id", "post_id"]);
+
+        let names = extract_path_param_names("/users");
+        assert_eq!(names, Vec::<&str>::new());
+
+        let names = extract_path_param_names("/users/{user_id}");
+        assert_eq!(names, vec!["user_id"]);
+    }
+
+    #[test]
+    fn test_extract_parameters_from_schema_path_params() {
+        let param_schema = json!({
+            "type": "object",
+            "properties": {
+                "user_id": { "type": "integer" },
+                "post_id": { "type": "integer" }
+            },
+            "required": ["user_id", "post_id"]
+        });
+
+        let result = extract_parameters_from_schema(&param_schema, "/users/{user_id}/posts/{post_id}");
+        assert!(result.is_ok());
+
+        let params = result.unwrap();
+        assert_eq!(params.len(), 2);
+
+        for param in params {
+            if let RefOr::T(p) = param {
+                assert!(matches!(p.parameter_in, ParameterIn::Path));
+                assert!(matches!(p.required, utoipa::openapi::Required::True));
+            }
+        }
+    }
+
+    #[test]
+    fn test_extract_parameters_from_schema_query_params() {
+        let param_schema = json!({
+            "type": "object",
+            "properties": {
+                "page": { "type": "integer" },
+                "limit": { "type": "integer" },
+                "search": { "type": "string" }
+            },
+            "required": ["page"]
+        });
+
+        let result = extract_parameters_from_schema(&param_schema, "/users");
+        assert!(result.is_ok());
+
+        let params = result.unwrap();
+        assert_eq!(params.len(), 3);
+
+        for param in &params {
+            if let RefOr::T(p) = param {
+                assert!(matches!(p.parameter_in, ParameterIn::Query));
+            }
+        }
+
+        for param in params {
+            if let RefOr::T(p) = param {
+                if p.name == "page" {
+                    assert!(matches!(p.required, utoipa::openapi::Required::True));
+                } else {
+                    assert!(matches!(p.required, utoipa::openapi::Required::False));
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn test_extract_parameters_from_schema_mixed() {
+        let param_schema = json!({
+            "type": "object",
+            "properties": {
+                "user_id": { "type": "integer" },
+                "page": { "type": "integer" },
+                "limit": { "type": "integer" }
+            },
+            "required": ["user_id"]
+        });
+
+        let result = extract_parameters_from_schema(&param_schema, "/users/{user_id}");
+        assert!(result.is_ok());
+
+        let params = result.unwrap();
+        assert_eq!(params.len(), 3);
+
+        for param in params {
+            if let RefOr::T(p) = param {
+                if p.name == "user_id" {
+                    assert!(matches!(p.parameter_in, ParameterIn::Path));
+                    assert!(matches!(p.required, utoipa::openapi::Required::True));
+                } else {
+                    assert!(matches!(p.parameter_in, ParameterIn::Query));
+                    assert!(matches!(p.required, utoipa::openapi::Required::False));
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn test_extract_parameters_error_on_missing_properties() {
+        let param_schema = json!({
+            "type": "object"
+        });
+
+        let result = extract_parameters_from_schema(&param_schema, "/users");
+        assert!(result.is_err());
+        if let Err(err) = result {
+            assert!(err.contains("properties"));
+        }
+    }
+
+    #[test]
+    fn test_extract_parameters_with_format_specifiers() {
+        let param_schema = json!({
+            "type": "object",
+            "properties": {
+                "user_id": { "type": "string", "format": "uuid" },
+                "created_at": { "type": "string", "format": "date-time" },
+                "birth_date": { "type": "string", "format": "date" },
+                "email": { "type": "string", "format": "email" },
+                "website": { "type": "string", "format": "uri" }
+            },
+            "required": ["user_id"]
+        });
+
+        let result = extract_parameters_from_schema(&param_schema, "/users");
+        assert!(result.is_ok());
+
+        let params: Vec<RefOr<Parameter>> = result.unwrap();
+        assert_eq!(params.len(), 5);
+
+        for param in params {
+            if let RefOr::T(p) = param {
+                assert!(matches!(p.parameter_in, ParameterIn::Query));
+                if p.name == "user_id" {
+                    assert!(matches!(p.required, utoipa::openapi::Required::True));
+                } else {
+                    assert!(matches!(p.required, utoipa::openapi::Required::False));
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn test_extract_parameters_with_nullable_optional() {
+        let param_schema = json!({
+            "type": "object",
+            "properties": {
+                "search": { "type": "string" },
+                "filter": { "type": "string" }
+            },
+            "required": []
+        });
+
+        let result = extract_parameters_from_schema(&param_schema, "/items");
+        assert!(result.is_ok());
+
+        let params: Vec<RefOr<Parameter>> = result.unwrap();
+        assert_eq!(params.len(), 2);
+
+        for param in params {
+            if let RefOr::T(p) = param {
+                assert!(matches!(p.required, utoipa::openapi::Required::False));
+            }
+        }
+    }
+
+    #[test]
+    fn test_extract_parameters_array_parameter() {
+        let param_schema = json!({
+            "type": "object",
+            "properties": {
+                "tags": {
+                    "type": "array",
+                    "items": { "type": "string" }
+                },
+                "ids": {
+                    "type": "array",
+                    "items": { "type": "integer" }
+                }
+            },
+            "required": ["tags"]
+        });
+
+        let result = extract_parameters_from_schema(&param_schema, "/search");
+        assert!(result.is_ok());
+
+        let params: Vec<RefOr<Parameter>> = result.unwrap();
+        assert_eq!(params.len(), 2);
+
+        for param in params {
+            if let RefOr::T(p) = param {
+                if p.name == "tags" {
+                    assert!(matches!(p.required, utoipa::openapi::Required::True));
+                } else if p.name == "ids" {
+                    assert!(matches!(p.required, utoipa::openapi::Required::False));
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn test_extract_parameters_empty_properties() {
+        let param_schema = json!({
+            "type": "object",
+            "properties": {},
+            "required": []
+        });
+
+        let result = extract_parameters_from_schema(&param_schema, "/items");
+        assert!(result.is_ok());
+
+        let params: Vec<RefOr<Parameter>> = result.unwrap();
+        assert_eq!(params.len(), 0);
+    }
+
+    #[test]
+    fn test_extract_parameters_with_multiple_path_params() {
+        let param_schema = json!({
+            "type": "object",
+            "properties": {
+                "org_id": { "type": "string" },
+                "team_id": { "type": "string" },
+                "member_id": { "type": "string" },
+                "page": { "type": "integer" }
+            },
+            "required": ["org_id", "team_id", "member_id"]
+        });
+
+        let result =
+            extract_parameters_from_schema(&param_schema, "/orgs/{org_id}/teams/{team_id}/members/{member_id}");
+        assert!(result.is_ok());
+
+        let params: Vec<RefOr<Parameter>> = result.unwrap();
+        assert_eq!(params.len(), 4);
+
+        let mut path_count: i32 = 0;
+        let mut query_count: i32 = 0;
+
+        for param in params {
+            if let RefOr::T(p) = param {
+                if matches!(p.parameter_in, ParameterIn::Path) {
+                    path_count += 1;
+                    assert!(matches!(p.required, utoipa::openapi::Required::True));
+                } else {
+                    query_count += 1;
+                }
+            }
+        }
+
+        assert_eq!(path_count, 3);
+        assert_eq!(query_count, 1);
+    }
+
+    #[test]
+    fn test_extract_parameters_with_numeric_types() {
+        let param_schema = json!({
+            "type": "object",
+            "properties": {
+                "count": { "type": "integer" },
+                "score": { "type": "number" },
+                "active": { "type": "boolean" }
+            },
+            "required": ["count"]
+        });
+
+        let result = extract_parameters_from_schema(&param_schema, "/stats");
+        assert!(result.is_ok());
+
+        let params: Vec<RefOr<Parameter>> = result.unwrap();
+        assert_eq!(params.len(), 3);
+
+        for param in params {
+            if let RefOr::T(p) = param {
+                assert!(matches!(p.parameter_in, ParameterIn::Query));
+                if p.name == "count" {
+                    assert!(matches!(p.required, utoipa::openapi::Required::True));
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn test_extract_parameters_required_field_parsing() {
+        let param_schema = json!({
+            "type": "object",
+            "properties": {
+                "id": { "type": "integer" },
+                "name": { "type": "string" },
+                "email": { "type": "string" },
+                "age": { "type": "integer" }
+            },
+            "required": ["id", "name"]
+        });
+
+        let result = extract_parameters_from_schema(&param_schema, "/items");
+        assert!(result.is_ok());
+
+        let params: Vec<RefOr<Parameter>> = result.unwrap();
+        assert_eq!(params.len(), 4);
+
+        let required_names: Vec<&str> = vec!["id", "name"];
+
+        for param in params {
+            if let RefOr::T(p) = param {
+                if required_names.contains(&p.name.as_str()) {
+                    assert!(matches!(p.required, utoipa::openapi::Required::True));
+                } else {
+                    assert!(matches!(p.required, utoipa::openapi::Required::False));
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn test_extract_parameters_single_path_param_override_required() {
+        let param_schema = json!({
+            "type": "object",
+            "properties": {
+                "id": { "type": "integer" },
+                "query": { "type": "string" }
+            },
+            "required": ["query"]
+        });
+
+        let result = extract_parameters_from_schema(&param_schema, "/items/{id}");
+        assert!(result.is_ok());
+
+        let params: Vec<RefOr<Parameter>> = result.unwrap();
+        assert_eq!(params.len(), 2);
+
+        for param in params {
+            if let RefOr::T(p) = param {
+                if p.name == "id" {
+                    assert!(matches!(p.parameter_in, ParameterIn::Path));
+                    assert!(matches!(p.required, utoipa::openapi::Required::True));
+                } else if p.name == "query" {
+                    assert!(matches!(p.parameter_in, ParameterIn::Query));
+                    assert!(matches!(p.required, utoipa::openapi::Required::True));
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn test_extract_parameters_nested_object_schema() {
+        let param_schema = json!({
+            "type": "object",
+            "properties": {
+                "filter": {
+                    "type": "object",
+                    "properties": {
+                        "status": { "type": "string" },
+                        "priority": { "type": "integer" }
+                    },
+                    "required": ["status"]
+                }
+            },
+            "required": ["filter"]
+        });
+
+        let result = extract_parameters_from_schema(&param_schema, "/tasks");
+        assert!(result.is_ok());
+
+        let params: Vec<RefOr<Parameter>> = result.unwrap();
+        assert_eq!(params.len(), 1);
+
+        if let Some(RefOr::T(p)) = params.first() {
+            assert_eq!(p.name, "filter");
+            assert!(matches!(p.parameter_in, ParameterIn::Query));
+            assert!(matches!(p.required, utoipa::openapi::Required::True));
+        }
+    }
+
+    #[test]
+    fn test_extract_parameters_with_special_characters_in_names() {
+        let param_schema = json!({
+            "type": "object",
+            "properties": {
+                "user_id": { "type": "string" },
+                "api_key": { "type": "string" },
+                "x_custom_header": { "type": "string" }
+            },
+            "required": ["user_id"]
+        });
+
+        let result = extract_parameters_from_schema(&param_schema, "/data");
+        assert!(result.is_ok());
+
+        let params: Vec<RefOr<Parameter>> = result.unwrap();
+        assert_eq!(params.len(), 3);
+
+        let param_names: Vec<String> = params
+            .iter()
+            .filter_map(|p| match p {
+                RefOr::T(param) => Some(param.name.clone()),
+                RefOr::Ref(_) => None,
+            })
+            .collect();
+
+        assert!(param_names.contains(&"user_id".to_string()));
+        assert!(param_names.contains(&"api_key".to_string()));
+        assert!(param_names.contains(&"x_custom_header".to_string()));
+    }
+
+    #[test]
+    fn test_extract_parameters_with_mismatched_required_field() {
+        let param_schema = json!({
+            "type": "object",
+            "properties": {
+                "id": { "type": "integer" },
+                "name": { "type": "string" }
+            },
+            "required": ["id", "nonexistent_field"]
+        });
+
+        let result = extract_parameters_from_schema(&param_schema, "/items");
+        assert!(result.is_ok());
+
+        let params: Vec<RefOr<Parameter>> = result.unwrap();
+        assert_eq!(params.len(), 2);
+
+        for param in params {
+            if let RefOr::T(p) = param {
+                if p.name == "id" {
+                    assert!(matches!(p.required, utoipa::openapi::Required::True));
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn test_extract_path_param_names_with_special_segments() {
+        let names: Vec<&str> =
+            extract_path_param_names("/api/v1/users/{user_id}/posts/{post_id}/comments/{comment_id}");
+        assert_eq!(names, vec!["user_id", "post_id", "comment_id"]);
+    }
+
+    #[test]
+    fn test_extract_path_param_names_no_params() {
+        let names: Vec<&str> = extract_path_param_names("/api/users/list");
+        assert!(names.is_empty());
+    }
+
+    #[test]
+    fn test_extract_path_param_names_single_param_end() {
+        let names: Vec<&str> = extract_path_param_names("/resource/{id}");
+        assert_eq!(names, vec!["id"]);
+    }
+
+    #[test]
+    fn test_extract_path_param_names_numeric_param_names() {
+        let names: Vec<&str> = extract_path_param_names("/items/{id1}/sub/{id2}");
+        assert_eq!(names, vec!["id1", "id2"]);
+    }
+}