fix: resolve $ref parameters, merge path-item params, avoid url variable collision, and use r#type raw identifiers

Issue #2: Fix three bugs when ingesting specs with path-item-level parameters:
- Resolve $ref parameter references via components/parameters lookup
- Merge path-item-level parameters into operations (operation params take precedence)
- Rename internal `url` variable to `request_url` to avoid collision with params named `url`

Issue #3: Use raw identifiers (r#type) instead of suffixed names (type_) for Rust
keyword field names. This is more idiomatic and avoids polluting the API surface
with trailing underscores. Serde rename attributes are still emitted where the
Rust field name differs from the JSON key after stripping the r# prefix.

Closes #2, closes #3

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

Author: lightsofapollo

src/analysis.rs

@@ -530,6 +530,7 @@ pub struct SchemaAnalyzer {
     resolved_cache: BTreeMap<String, AnalyzedSchema>,
     openapi_spec: Value,
     current_schema_name: Option<String>,
+    component_parameters: BTreeMap<String, crate::openapi::Parameter>,
 }
 
 impl SchemaAnalyzer {
@@ -538,11 +539,19 @@ impl SchemaAnalyzer {
             serde_json::from_value(openapi_spec.clone()).map_err(GeneratorError::ParseError)?;
         let schemas = Self::extract_schemas(&spec)?;
 
+        let component_parameters = spec
+            .components
+            .as_ref()
+            .and_then(|c| c.parameters.as_ref())
+            .cloned()
+            .unwrap_or_default();
+
         Ok(Self {
             schemas,
             resolved_cache: BTreeMap::new(),
             openapi_spec,
             current_schema_name: None,
+            component_parameters,
         })
     }
 
@@ -3388,6 +3397,7 @@ impl SchemaAnalyzer {
                         method,
                         path,
                         operation,
+                        path_item.parameters.as_ref(),
                         analysis,
                     )?;
                     analysis.operations.insert(operation_id, op_info);
@@ -3443,6 +3453,7 @@ impl SchemaAnalyzer {
         method: &str,
         path: &str,
         operation: &crate::openapi::Operation,
+        path_item_parameters: Option<&Vec<crate::openapi::Parameter>>,
         _analysis: &mut SchemaAnalysis,
     ) -> Result<OperationInfo> {
         let mut op_info = OperationInfo {
@@ -3510,15 +3521,33 @@ impl SchemaAnalyzer {
             }
         }
 
-        // Extract parameters
+        // Extract parameters (operation-level first, then merge path-item-level)
         if let Some(parameters) = &operation.parameters {
             for param in parameters {
-                if let Some(param_info) = self.analyze_parameter(param)? {
+                let resolved = self.resolve_parameter(param);
+                if let Some(param_info) = self.analyze_parameter(&resolved)? {
                     op_info.parameters.push(param_info);
                 }
             }
         }
 
+        // Merge path-item-level parameters (operation params take precedence per OpenAPI spec)
+        if let Some(path_params) = path_item_parameters {
+            let existing_keys: std::collections::HashSet<(String, String)> = op_info
+                .parameters
+                .iter()
+                .map(|p| (p.name.clone(), p.location.clone()))
+                .collect();
+            for param in path_params {
+                let resolved = self.resolve_parameter(param);
+                if let Some(param_info) = self.analyze_parameter(&resolved)? {
+                    if !existing_keys.contains(&(param_info.name.clone(), param_info.location.clone())) {
+                        op_info.parameters.push(param_info);
+                    }
+                }
+            }
+        }
+
         Ok(op_info)
     }
 
@@ -3566,6 +3595,22 @@ impl SchemaAnalyzer {
         Ok(synthetic_name)
     }
 
+    /// Resolve a parameter reference ($ref) to the actual parameter definition.
+    /// Returns the resolved parameter, or the original if it's not a reference.
+    fn resolve_parameter<'a>(
+        &'a self,
+        param: &'a crate::openapi::Parameter,
+    ) -> std::borrow::Cow<'a, crate::openapi::Parameter> {
+        if let Some(ref_str) = param.extra.get("$ref").and_then(|v| v.as_str()) {
+            if let Some(param_name) = ref_str.strip_prefix("#/components/parameters/") {
+                if let Some(resolved) = self.component_parameters.get(param_name) {
+                    return std::borrow::Cow::Borrowed(resolved);
+                }
+            }
+        }
+        std::borrow::Cow::Borrowed(param)
+    }
+
     /// Analyze a parameter
     fn analyze_parameter(
         &self,

src/client_generator.rs

@@ -406,7 +406,7 @@ impl CodeGenerator {
                 #url_construction
 
                 let mut req = self.http_client
-                    .#http_method(url)
+                    .#http_method(request_url)
                     #request_body;
 
                 #query_params
@@ -444,7 +444,7 @@ impl CodeGenerator {
         for param in query_params {
             // Use snake_case for Rust variable name with keyword escaping
             let param_name_snake = self.sanitize_param_name(&param.name);
-            let param_name = syn::Ident::new(&param_name_snake, proc_macro2::Span::call_site());
+            let param_name = Self::to_field_ident(&param_name_snake);
 
             // Use the original parameter name from OpenAPI spec as the query string key
             let param_key = &param.name;
@@ -540,7 +540,7 @@ impl CodeGenerator {
         for param in &op.parameters {
             if param.location == "path" {
                 let param_name_snake = self.sanitize_param_name(&param.name);
-                let param_name = syn::Ident::new(&param_name_snake, proc_macro2::Span::call_site());
+                let param_name = Self::to_field_ident(&param_name_snake);
                 let param_type = self.get_param_rust_type(param);
                 params.push(quote! { #param_name: #param_type });
             }
@@ -550,7 +550,7 @@ impl CodeGenerator {
         for param in &op.parameters {
             if param.location == "query" {
                 let param_name_snake = self.sanitize_param_name(&param.name);
-                let param_name = syn::Ident::new(&param_name_snake, proc_macro2::Span::call_site());
+                let param_name = Self::to_field_ident(&param_name_snake);
                 let param_type = self.get_param_rust_type(param);
 
                 // Query parameters should be Option unless explicitly required
@@ -714,7 +714,7 @@ impl CodeGenerator {
             self.generate_url_with_params(path, op)
         } else {
             quote! {
-                let url = format!("{}{}", self.base_url, #path);
+                let request_url = format!("{}{}", self.base_url, #path);
             }
         }
     }
@@ -740,8 +740,7 @@ impl CodeGenerator {
 
                 // Use snake_case for the Rust variable name with keyword escaping
                 let param_name_snake = self.sanitize_param_name(&param.name);
-                let param_ident =
-                    syn::Ident::new(&param_name_snake, proc_macro2::Span::call_site());
+                let param_ident = Self::to_field_ident(&param_name_snake);
 
                 // Use .as_ref() for string types to handle impl AsRef<str>
                 if param.rust_type == "String" {
@@ -755,66 +754,24 @@ impl CodeGenerator {
         if format_args.is_empty() {
             // No path parameters found, use simple format
             quote! {
-                let url = format!("{}{}", self.base_url, #path);
+                let request_url = format!("{}{}", self.base_url, #path);
             }
         } else {
             // Build format call with path parameters
             quote! {
-                let url = format!("{}{}", self.base_url, format!(#format_string, #(#format_args),*));
+                let request_url = format!("{}{}", self.base_url, format!(#format_string, #(#format_args),*));
             }
         }
     }
 
-    /// Sanitize a parameter name by escaping Rust reserved keywords
+    /// Sanitize a parameter name by escaping Rust reserved keywords with raw identifiers
     fn sanitize_param_name(&self, name: &str) -> String {
         let snake_case = name.to_snake_case();
-        match snake_case.as_str() {
-            "type" => "type_".to_string(),
-            "match" => "match_".to_string(),
-            "fn" => "fn_".to_string(),
-            "impl" => "impl_".to_string(),
-            "trait" => "trait_".to_string(),
-            "struct" => "struct_".to_string(),
-            "enum" => "enum_".to_string(),
-            "mod" => "mod_".to_string(),
-            "use" => "use_".to_string(),
-            "pub" => "pub_".to_string(),
-            "const" => "const_".to_string(),
-            "static" => "static_".to_string(),
-            "let" => "let_".to_string(),
-            "mut" => "mut_".to_string(),
-            "ref" => "ref_".to_string(),
-            "move" => "move_".to_string(),
-            "return" => "return_".to_string(),
-            "if" => "if_".to_string(),
-            "else" => "else_".to_string(),
-            "while" => "while_".to_string(),
-            "for" => "for_".to_string(),
-            "loop" => "loop_".to_string(),
-            "break" => "break_".to_string(),
-            "continue" => "continue_".to_string(),
-            "self" => "self_".to_string(),
-            "super" => "super_".to_string(),
-            "crate" => "crate_".to_string(),
-            "async" => "async_".to_string(),
-            "await" => "await_".to_string(),
-            "override" => "override_".to_string(),
-            "box" => "box_".to_string(),
-            "dyn" => "dyn_".to_string(),
-            "where" => "where_".to_string(),
-            "in" => "in_".to_string(),
-            "abstract" => "abstract_".to_string(),
-            "become" => "become_".to_string(),
-            "do" => "do_".to_string(),
-            "final" => "final_".to_string(),
-            "macro" => "macro_".to_string(),
-            "priv" => "priv_".to_string(),
-            "try" => "try_".to_string(),
-            "typeof" => "typeof_".to_string(),
-            "unsized" => "unsized_".to_string(),
-            "virtual" => "virtual_".to_string(),
-            "yield" => "yield_".to_string(),
-            _ => snake_case,
+        if Self::is_rust_keyword(&snake_case) {
+            format!("r#{snake_case}")
+        } else {
+            snake_case
         }
     }
+
 }

src/generator.rs

@@ -851,7 +851,7 @@ impl CodeGenerator {
                 }
             })
             .map(|(field_name, prop)| {
-                let field_ident = format_ident!("{}", self.to_rust_field_name(field_name));
+                let field_ident = Self::to_field_ident(&self.to_rust_field_name(field_name));
                 let is_required = required.contains(field_name);
                 let field_type =
                     self.generate_field_type(&schema.name, field_name, prop, is_required, analysis);
@@ -1249,9 +1249,11 @@ impl CodeGenerator {
     ) -> TokenStream {
         let mut attrs = Vec::new();
 
-        // Generate rename attribute if field name is not valid Rust identifier
+        // Generate rename attribute if field name differs from Rust identifier
+        // Strip r# prefix for comparison since serde handles raw idents transparently
         let rust_field_name = self.to_rust_field_name(field_name);
-        if rust_field_name != field_name {
+        let comparison_name = rust_field_name.strip_prefix("r#").unwrap_or(&rust_field_name);
+        if comparison_name != field_name {
             attrs.push(quote! { rename = #field_name });
         }
 
@@ -1610,57 +1612,34 @@ impl CodeGenerator {
             result = format!("field_{result}");
         }
 
-        // Handle reserved keywords
-        match result.as_str() {
-            "type" => "type_".to_string(),
-            "match" => "match_".to_string(),
-            "fn" => "fn_".to_string(),
-            "struct" => "struct_".to_string(),
-            "enum" => "enum_".to_string(),
-            "impl" => "impl_".to_string(),
-            "trait" => "trait_".to_string(),
-            "mod" => "mod_".to_string(),
-            "use" => "use_".to_string(),
-            "pub" => "pub_".to_string(),
-            "const" => "const_".to_string(),
-            "static" => "static_".to_string(),
-            "let" => "let_".to_string(),
-            "mut" => "mut_".to_string(),
-            "ref" => "ref_".to_string(),
-            "move" => "move_".to_string(),
-            "return" => "return_".to_string(),
-            "if" => "if_".to_string(),
-            "else" => "else_".to_string(),
-            "while" => "while_".to_string(),
-            "for" => "for_".to_string(),
-            "loop" => "loop_".to_string(),
-            "break" => "break_".to_string(),
-            "continue" => "continue_".to_string(),
-            // Handle some common edge cases
-            "self" => "self_".to_string(),
-            "super" => "super_".to_string(),
-            "crate" => "crate_".to_string(),
-            "async" => "async_".to_string(),
-            "await" => "await_".to_string(),
-            // Reserved keywords for edition 2018+
-            "override" => "override_".to_string(),
-            "box" => "box_".to_string(),
-            "dyn" => "dyn_".to_string(),
-            "where" => "where_".to_string(),
-            "in" => "in_".to_string(),
-            // Reserved for future use
-            "abstract" => "abstract_".to_string(),
-            "become" => "become_".to_string(),
-            "do" => "do_".to_string(),
-            "final" => "final_".to_string(),
-            "macro" => "macro_".to_string(),
-            "priv" => "priv_".to_string(),
-            "try" => "try_".to_string(),
-            "typeof" => "typeof_".to_string(),
-            "unsized" => "unsized_".to_string(),
-            "virtual" => "virtual_".to_string(),
-            "yield" => "yield_".to_string(),
-            _ => result,
+        // Handle reserved keywords using raw identifiers (r#keyword)
+        if Self::is_rust_keyword(&result) {
+            format!("r#{result}")
+        } else {
+            result
+        }
+    }
+
+    /// Check if a string is a Rust keyword that needs raw identifier treatment
+    pub fn is_rust_keyword(s: &str) -> bool {
+        matches!(
+            s,
+            "type" | "match" | "fn" | "struct" | "enum" | "impl" | "trait" | "mod"
+            | "use" | "pub" | "const" | "static" | "let" | "mut" | "ref" | "move"
+            | "return" | "if" | "else" | "while" | "for" | "loop" | "break"
+            | "continue" | "self" | "super" | "crate" | "async" | "await"
+            | "override" | "box" | "dyn" | "where" | "in"
+            | "abstract" | "become" | "do" | "final" | "macro" | "priv" | "try"
+            | "typeof" | "unsized" | "virtual" | "yield"
+        )
+    }
+
+    /// Create a proc_macro2::Ident from a field name, handling r# raw identifiers
+    pub fn to_field_ident(name: &str) -> proc_macro2::Ident {
+        if let Some(raw) = name.strip_prefix("r#") {
+            proc_macro2::Ident::new_raw(raw, proc_macro2::Span::call_site())
+        } else {
+            proc_macro2::Ident::new(name, proc_macro2::Span::call_site())
         }
     }
 

src/openapi.rs

@@ -25,6 +25,7 @@ pub struct Info {
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct Components {
     pub schemas: Option<BTreeMap<String, Schema>>,
+    pub parameters: Option<BTreeMap<String, Parameter>>,
     #[serde(flatten)]
     pub extra: BTreeMap<String, Value>,
 }

src/snapshots/openapi_to_rust__test_helpers__beta_tools_array_union_test.snap

@@ -36,15 +36,15 @@ pub struct BetaTool {
     pub description: Option<String>,
     pub input_schema: BetaInputSchema,
     pub name: String,
-    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
-    pub type_: Option<serde_json::Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub r#type: Option<serde_json::Value>,
 }
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct BetaInputSchema {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub properties: Option<serde_json::Value>,
-    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
-    pub type_: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub r#type: Option<String>,
 }
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct BetaComputerUseTool {
@@ -53,6 +53,6 @@ pub struct BetaComputerUseTool {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub display_width_px: Option<i64>,
     pub name: String,
-    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
-    pub type_: Option<serde_json::Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub r#type: Option<serde_json::Value>,
 }

src/snapshots/openapi_to_rust__test_helpers__content_union_structured.snap

@@ -28,6 +28,5 @@ pub type ContentBlockArray = Vec<ContentBlock>;
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct ContentBlock {
     pub text: String,
-    #[serde(rename = "type")]
-    pub type_: String,
+    pub r#type: String,
 }

src/snapshots/openapi_to_rust__test_helpers__create_response_input_typing.snap

@@ -27,8 +27,7 @@ pub enum CreateResponseInput {
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct InputItem {
     pub content: String,
-    #[serde(rename = "type")]
-    pub type_: InputItemType,
+    pub r#type: InputItemType,
 }
 #[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize, Default)]
 pub enum InputItemType {