fastmcp 2.1.0__py3-none-any.whl → 2.1.2__py3-none-any.whl

fastmcp/utilities/openapi.py

@@ -14,6 +14,16 @@ from openapi_pydantic import (
     Response,
     Schema,
 )
+
+# Import OpenAPI 3.0 models as well
+from openapi_pydantic.v3.v3_0 import OpenAPI as OpenAPI_30
+from openapi_pydantic.v3.v3_0 import Operation as Operation_30
+from openapi_pydantic.v3.v3_0 import Parameter as Parameter_30
+from openapi_pydantic.v3.v3_0 import PathItem as PathItem_30
+from openapi_pydantic.v3.v3_0 import Reference as Reference_30
+from openapi_pydantic.v3.v3_0 import RequestBody as RequestBody_30
+from openapi_pydantic.v3.v3_0 import Response as Response_30
+from openapi_pydantic.v3.v3_0 import Schema as Schema_30
 from pydantic import BaseModel, Field, ValidationError
 
 from fastmcp.utilities import openapi
@@ -140,412 +150,694 @@ def _resolve_ref(
     return item
 
 
-def _extract_schema_as_dict(
-    schema_obj: Schema | Reference, openapi: OpenAPI
-) -> JsonSchema:
-    """Resolves a schema/reference and returns it as a dictionary."""
-    resolved_schema = _resolve_ref(schema_obj, openapi)
-    if isinstance(resolved_schema, Schema):
-        # Using exclude_none=True might be better than exclude_unset sometimes
-        return resolved_schema.model_dump(mode="json", by_alias=True, exclude_none=True)
-    elif isinstance(resolved_schema, dict):
-        logger.warning(
-            "Resolved schema reference resulted in a dict, not a Schema model."
-        )
-        return resolved_schema
-    else:
-        ref_str = getattr(schema_obj, "ref", "unknown")
-        logger.warning(
-            f"Expected Schema after resolving ref '{ref_str}', got {type(resolved_schema)}. Returning empty dict."
-        )
-        return {}
-
-
-def _convert_to_parameter_location(param_in: str) -> ParameterLocation:
-    """Convert string parameter location to our ParameterLocation type."""
-    if param_in == "path":
-        return "path"
-    elif param_in == "query":
-        return "query"
-    elif param_in == "header":
-        return "header"
-    elif param_in == "cookie":
-        return "cookie"
-    else:
-        logger.warning(f"Unknown parameter location: {param_in}, defaulting to 'query'")
-        return "query"
-
-
-def _extract_parameters(
-    operation_params: list[Parameter | Reference] | None,
-    path_item_params: list[Parameter | Reference] | None,
-    openapi: OpenAPI,
-) -> list[ParameterInfo]:
-    """Extracts and resolves parameters using corrected attribute names."""
-    extracted_params: list[ParameterInfo] = []
-    seen_params: dict[
-        tuple[str, str], bool
-    ] = {}  # Use string keys to avoid type issues
-    all_params_refs = (operation_params or []) + (path_item_params or [])
-
-    for param_or_ref in all_params_refs:
-        try:
-            parameter = cast(Parameter, _resolve_ref(param_or_ref, openapi))
-            if not isinstance(parameter, Parameter):
-                # ... (error logging remains the same)
-                continue
-
-            # --- *** CORRECTED ATTRIBUTE ACCESS HERE *** ---
-            param_in = parameter.param_in  # CORRECTED: Use 'param_in'
-            param_location = _convert_to_parameter_location(param_in)
-            param_schema_obj = parameter.param_schema  # CORRECTED: Use 'param_schema'
-            # --- *** ---
+# --- Main Parsing Function ---
+# (No changes needed in the main loop logic, only in the helpers it calls)
+def parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRoute]:
+    """
+    Parses an OpenAPI schema dictionary into a list of HTTPRoute objects
+    using the openapi-pydantic library.
 
-            param_key = (parameter.name, param_in)
-            if param_key in seen_params:
-                continue
-            seen_params[param_key] = True
-
-            param_schema_dict = {}
-            if param_schema_obj:  # Check if schema exists
-                param_schema_dict = _extract_schema_as_dict(param_schema_obj, openapi)
-            elif parameter.content:
-                # Handle complex parameters with 'content'
-                first_media_type = next(iter(parameter.content.values()), None)
-                if (
-                    first_media_type and first_media_type.media_type_schema
-                ):  # CORRECTED: Use 'media_type_schema'
-                    param_schema_dict = _extract_schema_as_dict(
-                        first_media_type.media_type_schema, openapi
-                    )
-                    logger.debug(
-                        f"Parameter '{parameter.name}' using schema from 'content' field."
-                    )
+    Supports both OpenAPI 3.0.x and 3.1.x versions.
+    """
+    # Check OpenAPI version to use appropriate model
+    openapi_version = openapi_dict.get("openapi", "")
 
-            # Manually create ParameterInfo instance using correct field names
-            param_info = ParameterInfo(
-                name=parameter.name,
-                location=param_location,  # Use converted parameter location
-                required=parameter.required,
-                schema=param_schema_dict,  # Populate 'schema' field in IR
-                description=parameter.description,
+    try:
+        if openapi_version.startswith("3.0"):
+            # Use OpenAPI 3.0 models
+            openapi_30 = OpenAPI_30.model_validate(openapi_dict)
+            logger.info(
+                f"Successfully parsed OpenAPI 3.0 schema version: {openapi_30.openapi}"
             )
-            extracted_params.append(param_info)
-
-        except (
-            ValidationError,
-            ValueError,
-            AttributeError,
-            TypeError,
-        ) as e:  # Added TypeError
-            param_name = getattr(
-                param_or_ref, "name", getattr(param_or_ref, "ref", "unknown")
+            parser = OpenAPI30Parser(openapi_30)
+            return parser.parse()
+        else:
+            # Default to OpenAPI 3.1 models
+            openapi_31 = OpenAPI.model_validate(openapi_dict)
+            logger.info(
+                f"Successfully parsed OpenAPI 3.1 schema version: {openapi_31.openapi}"
             )
-            logger.error(
-                f"Failed to extract parameter '{param_name}': {e}", exc_info=False
+            parser = OpenAPI31Parser(openapi_31)
+            return parser.parse()
+    except ValidationError as e:
+        logger.error(f"OpenAPI schema validation failed: {e}")
+        error_details = e.errors()
+        logger.error(f"Validation errors: {error_details}")
+        raise ValueError(f"Invalid OpenAPI schema: {error_details}") from e
+
+
+# Base parser class for shared functionality
+class BaseOpenAPIParser:
+    """Base class for OpenAPI parsers with common functionality."""
+
+    def _convert_to_parameter_location(self, param_in: str) -> ParameterLocation:
+        """Convert string parameter location to our ParameterLocation type."""
+        if param_in == "path":
+            return "path"
+        elif param_in == "query":
+            return "query"
+        elif param_in == "header":
+            return "header"
+        elif param_in == "cookie":
+            return "cookie"
+        else:
+            logger.warning(
+                f"Unknown parameter location: {param_in}, defaulting to 'query'"
             )
+            return "query"
 
-    return extracted_params
 
+class OpenAPI31Parser(BaseOpenAPIParser):
+    """Parser for OpenAPI 3.1 schemas."""
 
-def _extract_request_body(
-    request_body_or_ref: RequestBody | Reference | None, openapi: OpenAPI
-) -> RequestBodyInfo | None:
-    """Extracts and resolves the request body using corrected attribute names."""
-    if not request_body_or_ref:
-        return None
-    try:
-        request_body = cast(RequestBody, _resolve_ref(request_body_or_ref, openapi))
-        if not isinstance(request_body, RequestBody):
-            # ... (error logging remains the same)
-            return None
+    def __init__(self, openapi: OpenAPI):
+        self.openapi = openapi
 
-        content_schemas: dict[str, JsonSchema] = {}
-        if request_body.content:
-            for media_type_str, media_type_obj in request_body.content.items():
-                # --- *** CORRECTED ATTRIBUTE ACCESS HERE *** ---
-                if (
-                    isinstance(media_type_obj, MediaType)
-                    and media_type_obj.media_type_schema
-                ):  # CORRECTED: Use 'media_type_schema'
-                    # --- *** ---
+    def parse(self) -> list[HTTPRoute]:
+        """Parse an OpenAPI 3.1 schema into HTTP routes."""
+        routes: list[HTTPRoute] = []
+
+        if not self.openapi.paths:
+            logger.warning("OpenAPI schema has no paths defined.")
+            return []
+
+        for path_str, path_item_obj in self.openapi.paths.items():
+            if not isinstance(path_item_obj, PathItem):
+                logger.warning(
+                    f"Skipping invalid path item object for path '{path_str}' (type: {type(path_item_obj)})"
+                )
+                continue
+
+            path_level_params = path_item_obj.parameters
+
+            # Iterate through possible HTTP methods defined in the PathItem model fields
+            # Use model_fields from the class, not the instance
+            for method_lower in PathItem.model_fields.keys():
+                if method_lower not in [
+                    "get",
+                    "put",
+                    "post",
+                    "delete",
+                    "options",
+                    "head",
+                    "patch",
+                    "trace",
+                ]:
+                    continue
+
+                operation: Operation | None = getattr(path_item_obj, method_lower, None)
+
+                if operation and isinstance(operation, Operation):
+                    method_upper = cast(HttpMethod, method_lower.upper())
+                    logger.debug(f"Processing operation: {method_upper} {path_str}")
                     try:
-                        # Use the corrected attribute here as well
-                        schema_dict = _extract_schema_as_dict(
-                            media_type_obj.media_type_schema, openapi
+                        parameters = self._extract_parameters(
+                            operation.parameters, path_level_params
+                        )
+                        request_body_info = self._extract_request_body(
+                            operation.requestBody
+                        )
+                        responses = self._extract_responses(operation.responses)
+
+                        route = HTTPRoute(
+                            path=path_str,
+                            method=method_upper,
+                            operation_id=operation.operationId,
+                            summary=operation.summary,
+                            description=operation.description,
+                            tags=operation.tags or [],
+                            parameters=parameters,
+                            request_body=request_body_info,
+                            responses=responses,
                         )
-                        content_schemas[media_type_str] = schema_dict
-                    except ValueError as schema_err:
+                        routes.append(route)
+                        logger.info(
+                            f"Successfully extracted route: {method_upper} {path_str}"
+                        )
+                    except Exception as op_error:
+                        op_id = operation.operationId or "unknown"
                         logger.error(
-                            f"Failed to extract schema for media type '{media_type_str}' in request body: {schema_err}"
+                            f"Failed to process operation {method_upper} {path_str} (ID: {op_id}): {op_error}",
+                            exc_info=True,
                         )
-                elif not isinstance(media_type_obj, MediaType):
-                    logger.warning(
-                        f"Skipping invalid media type object for '{media_type_str}' (type: {type(media_type_obj)}) in request body."
-                    )
-                elif not media_type_obj.media_type_schema:  # Corrected check
-                    logger.warning(
-                        f"Skipping media type '{media_type_str}' in request body because it lacks a schema."
+
+        logger.info(f"Finished parsing. Extracted {len(routes)} HTTP routes.")
+        return routes
+
+    def _resolve_ref(
+        self, item: Reference | Schema | Parameter | RequestBody | Any
+    ) -> Any:
+        """Resolves a potential Reference object to its target definition."""
+        if isinstance(item, Reference):
+            ref_str = item.ref
+            try:
+                if not ref_str.startswith("#/"):
+                    raise ValueError(
+                        f"External or non-local reference not supported: {ref_str}"
                     )
+                parts = ref_str.strip("#/").split("/")
+                target = self.openapi
+                for part in parts:
+                    if part.isdigit() and isinstance(target, list):
+                        target = target[int(part)]
+                    elif isinstance(target, BaseModel):
+                        # Use model_extra for fields not explicitly defined (like components types)
+                        # Check class fields first, then model_extra
+                        if part in target.__class__.model_fields:
+                            target = getattr(target, part, None)
+                        elif target.model_extra and part in target.model_extra:
+                            target = target.model_extra[part]
+                        else:
+                            # Special handling for components sub-types common structure
+                            if part == "components" and hasattr(target, "components"):
+                                target = getattr(target, "components")
+                            elif hasattr(target, part):  # Fallback check
+                                target = getattr(target, part, None)
+                            else:
+                                target = None  # Part not found
+                    elif isinstance(target, dict):
+                        target = target.get(part)
+                    else:
+                        raise ValueError(
+                            f"Cannot traverse part '{part}' in reference '{ref_str}' from type {type(target)}"
+                        )
+                    if target is None:
+                        raise ValueError(
+                            f"Reference part '{part}' not found in path '{ref_str}'"
+                        )
+                if isinstance(target, Reference):
+                    return self._resolve_ref(target)
+                return target
+            except (AttributeError, KeyError, IndexError, TypeError, ValueError) as e:
+                raise ValueError(f"Failed to resolve reference '{ref_str}': {e}") from e
+        return item
+
+    def _extract_schema_as_dict(self, schema_obj: Schema | Reference) -> JsonSchema:
+        """Resolves a schema/reference and returns it as a dictionary."""
+        resolved_schema = self._resolve_ref(schema_obj)
+        if isinstance(resolved_schema, Schema):
+            # Using exclude_none=True might be better than exclude_unset sometimes
+            return resolved_schema.model_dump(
+                mode="json", by_alias=True, exclude_none=True
+            )
+        elif isinstance(resolved_schema, dict):
+            logger.warning(
+                "Resolved schema reference resulted in a dict, not a Schema model."
+            )
+            return resolved_schema
+        else:
+            ref_str = getattr(schema_obj, "ref", "unknown")
+            logger.warning(
+                f"Expected Schema after resolving ref '{ref_str}', got {type(resolved_schema)}. Returning empty dict."
+            )
+            return {}
+
+    def _extract_parameters(
+        self,
+        operation_params: list[Parameter | Reference] | None,
+        path_item_params: list[Parameter | Reference] | None,
+    ) -> list[ParameterInfo]:
+        """Extracts and resolves parameters using corrected attribute names."""
+        extracted_params: list[ParameterInfo] = []
+        seen_params: dict[
+            tuple[str, str], bool
+        ] = {}  # Use string keys to avoid type issues
+        all_params_refs = (operation_params or []) + (path_item_params or [])
+
+        for param_or_ref in all_params_refs:
+            try:
+                parameter = cast(Parameter, self._resolve_ref(param_or_ref))
+                if not isinstance(parameter, Parameter):
+                    # ... (error logging remains the same)
+                    continue
 
-        return RequestBodyInfo(
-            required=request_body.required,
-            content_schema=content_schemas,
-            description=request_body.description,
-        )
-    except (ValidationError, ValueError, AttributeError) as e:
-        ref_name = getattr(request_body_or_ref, "ref", "unknown")
-        logger.error(
-            f"Failed to extract request body '{ref_name}': {e}", exc_info=False
-        )
-        return None
+                # --- *** CORRECTED ATTRIBUTE ACCESS HERE *** ---
+                param_in = parameter.param_in  # CORRECTED: Use 'param_in'
+                param_location = self._convert_to_parameter_location(param_in)
+                param_schema_obj = (
+                    parameter.param_schema
+                )  # CORRECTED: Use 'param_schema'
+                # --- *** ---
+
+                param_key = (parameter.name, param_in)
+                if param_key in seen_params:
+                    continue
+                seen_params[param_key] = True
+
+                param_schema_dict = {}
+                if param_schema_obj:  # Check if schema exists
+                    param_schema_dict = self._extract_schema_as_dict(param_schema_obj)
+                elif parameter.content:
+                    # Handle complex parameters with 'content'
+                    first_media_type = next(iter(parameter.content.values()), None)
+                    if (
+                        first_media_type and first_media_type.media_type_schema
+                    ):  # CORRECTED: Use 'media_type_schema'
+                        param_schema_dict = self._extract_schema_as_dict(
+                            first_media_type.media_type_schema
+                        )
+                        logger.debug(
+                            f"Parameter '{parameter.name}' using schema from 'content' field."
+                        )
 
+                # Manually create ParameterInfo instance using correct field names
+                param_info = ParameterInfo(
+                    name=parameter.name,
+                    location=param_location,  # Use converted parameter location
+                    required=parameter.required,
+                    schema=param_schema_dict,  # Populate 'schema' field in IR
+                    description=parameter.description,
+                )
+                extracted_params.append(param_info)
+
+            except (
+                ValidationError,
+                ValueError,
+                AttributeError,
+                TypeError,
+            ) as e:  # Added TypeError
+                param_name = getattr(
+                    param_or_ref, "name", getattr(param_or_ref, "ref", "unknown")
+                )
+                logger.error(
+                    f"Failed to extract parameter '{param_name}': {e}", exc_info=False
+                )
 
-def _extract_responses(
-    operation_responses: dict[str, Response | Reference] | None,
-    openapi: OpenAPI,
-) -> dict[str, ResponseInfo]:
-    """Extracts and resolves response information for an operation."""
-    extracted_responses: dict[str, ResponseInfo] = {}
-    if not operation_responses:
-        return extracted_responses
+        return extracted_params
 
-    for status_code, resp_or_ref in operation_responses.items():
+    def _extract_request_body(
+        self, request_body_or_ref: RequestBody | Reference | None
+    ) -> RequestBodyInfo | None:
+        """Extracts and resolves the request body using corrected attribute names."""
+        if not request_body_or_ref:
+            return None
         try:
-            response = cast(Response, _resolve_ref(resp_or_ref, openapi))
-            if not isinstance(response, Response):
-                ref_str = getattr(resp_or_ref, "ref", "unknown")
-                logger.warning(
-                    f"Expected Response after resolving ref '{ref_str}' for status code {status_code}, got {type(response)}. Skipping."
-                )
-                continue
+            request_body = cast(RequestBody, self._resolve_ref(request_body_or_ref))
+            if not isinstance(request_body, RequestBody):
+                # ... (error logging remains the same)
+                return None
 
             content_schemas: dict[str, JsonSchema] = {}
-            if response.content:
-                for media_type_str, media_type_obj in response.content.items():
+            if request_body.content:
+                for media_type_str, media_type_obj in request_body.content.items():
+                    # --- *** CORRECTED ATTRIBUTE ACCESS HERE *** ---
                     if (
                         isinstance(media_type_obj, MediaType)
                         and media_type_obj.media_type_schema
-                    ):
+                    ):  # CORRECTED: Use 'media_type_schema'
+                        # --- *** ---
                         try:
-                            schema_dict = _extract_schema_as_dict(
-                                media_type_obj.media_type_schema, openapi
+                            # Use the corrected attribute here as well
+                            schema_dict = self._extract_schema_as_dict(
+                                media_type_obj.media_type_schema
                             )
                             content_schemas[media_type_str] = schema_dict
                         except ValueError as schema_err:
                             logger.error(
-                                f"Failed to extract schema for media type '{media_type_str}' in response {status_code}: {schema_err}"
+                                f"Failed to extract schema for media type '{media_type_str}' in request body: {schema_err}"
                             )
+                    elif not isinstance(media_type_obj, MediaType):
+                        logger.warning(
+                            f"Skipping invalid media type object for '{media_type_str}' (type: {type(media_type_obj)}) in request body."
+                        )
+                    elif not media_type_obj.media_type_schema:  # Corrected check
+                        logger.warning(
+                            f"Skipping media type '{media_type_str}' in request body because it lacks a schema."
+                        )
 
-            resp_info = ResponseInfo(
-                description=response.description, content_schema=content_schemas
+            return RequestBodyInfo(
+                required=request_body.required,
+                content_schema=content_schemas,
+                description=request_body.description,
             )
-            extracted_responses[str(status_code)] = resp_info
-
         except (ValidationError, ValueError, AttributeError) as e:
-            ref_name = getattr(resp_or_ref, "ref", "unknown")
+            ref_name = getattr(request_body_or_ref, "ref", "unknown")
             logger.error(
-                f"Failed to extract response for status code {status_code} (ref: '{ref_name}'): {e}",
-                exc_info=False,
+                f"Failed to extract request body '{ref_name}': {e}", exc_info=False
             )
+            return None
 
-    return extracted_responses
+    def _extract_responses(
+        self,
+        operation_responses: dict[str, Response | Reference] | None,
+    ) -> dict[str, ResponseInfo]:
+        """Extracts and resolves response information for an operation."""
+        extracted_responses: dict[str, ResponseInfo] = {}
+        if not operation_responses:
+            return extracted_responses
+
+        for status_code, resp_or_ref in operation_responses.items():
+            try:
+                response = cast(Response, self._resolve_ref(resp_or_ref))
+                if not isinstance(response, Response):
+                    ref_str = getattr(resp_or_ref, "ref", "unknown")
+                    logger.warning(
+                        f"Expected Response after resolving ref '{ref_str}' for status code {status_code}, got {type(response)}. Skipping."
+                    )
+                    continue
+
+                content_schemas: dict[str, JsonSchema] = {}
+                if response.content:
+                    for media_type_str, media_type_obj in response.content.items():
+                        if (
+                            isinstance(media_type_obj, MediaType)
+                            and media_type_obj.media_type_schema
+                        ):
+                            try:
+                                schema_dict = self._extract_schema_as_dict(
+                                    media_type_obj.media_type_schema
+                                )
+                                content_schemas[media_type_str] = schema_dict
+                            except ValueError as schema_err:
+                                logger.error(
+                                    f"Failed to extract schema for media type '{media_type_str}' in response {status_code}: {schema_err}"
+                                )
+
+                resp_info = ResponseInfo(
+                    description=response.description, content_schema=content_schemas
+                )
+                extracted_responses[str(status_code)] = resp_info
+
+            except (ValidationError, ValueError, AttributeError) as e:
+                ref_name = getattr(resp_or_ref, "ref", "unknown")
+                logger.error(
+                    f"Failed to extract response for status code {status_code} "
+                    f"from reference '{ref_name}': {e}",
+                    exc_info=False,
+                )
 
+        return extracted_responses
 
-# --- Main Parsing Function ---
-# (No changes needed in the main loop logic, only in the helpers it calls)
-def parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRoute]:
-    """
-    Parses an OpenAPI schema dictionary into a list of HTTPRoute objects
-    using the openapi-pydantic library.
-    """
-    routes: list[HTTPRoute] = []
-    try:
-        openapi: OpenAPI = OpenAPI.model_validate(openapi_dict)
-        logger.info(f"Successfully parsed OpenAPI schema version: {openapi.openapi}")
-    except ValidationError as e:
-        logger.error(f"OpenAPI schema validation failed: {e}")
-        error_details = e.errors()
-        logger.error(f"Validation errors: {error_details}")
-        raise ValueError(f"Invalid OpenAPI schema: {error_details}") from e
 
-    if not openapi.paths:
-        logger.warning("OpenAPI schema has no paths defined.")
-        return []
+class OpenAPI30Parser(BaseOpenAPIParser):
+    """Parser for OpenAPI 3.0 schemas."""
 
-    for path_str, path_item_obj in openapi.paths.items():
-        if not isinstance(path_item_obj, PathItem):
-            logger.warning(
-                f"Skipping invalid path item object for path '{path_str}' (type: {type(path_item_obj)})"
-            )
-            continue
-
-        path_level_params = path_item_obj.parameters
-
-        # Iterate through possible HTTP methods defined in the PathItem model fields
-        # Use model_fields from the class, not the instance
-        for method_lower in PathItem.model_fields.keys():
-            if method_lower not in [
-                "get",
-                "put",
-                "post",
-                "delete",
-                "options",
-                "head",
-                "patch",
-                "trace",
-            ]:
+    def __init__(self, openapi: OpenAPI_30):
+        self.openapi = openapi
+
+    def parse(self) -> list[HTTPRoute]:
+        """Parse an OpenAPI 3.0 schema into HTTP routes."""
+        routes: list[HTTPRoute] = []
+
+        if not self.openapi.paths:
+            logger.warning("OpenAPI schema has no paths defined.")
+            return []
+
+        for path_str, path_item_obj in self.openapi.paths.items():
+            if not isinstance(path_item_obj, PathItem_30):
+                logger.warning(
+                    f"Skipping invalid path item object for path '{path_str}' (type: {type(path_item_obj)})"
+                )
                 continue
 
-            operation: Operation | None = getattr(path_item_obj, method_lower, None)
+            path_level_params = path_item_obj.parameters
+
+            # Iterate through possible HTTP methods defined in the PathItem model fields
+            # Use model_fields from the class, not the instance
+            for method_lower in PathItem_30.model_fields.keys():
+                if method_lower not in [
+                    "get",
+                    "put",
+                    "post",
+                    "delete",
+                    "options",
+                    "head",
+                    "patch",
+                    "trace",
+                ]:
+                    continue
+
+                operation: Operation_30 | None = getattr(
+                    path_item_obj, method_lower, None
+                )
 
-            if operation and isinstance(operation, Operation):
-                method_upper = cast(HttpMethod, method_lower.upper())
-                logger.debug(f"Processing operation: {method_upper} {path_str}")
-                try:
-                    parameters = _extract_parameters(
-                        operation.parameters, path_level_params, openapi
-                    )
-                    request_body_info = _extract_request_body(
-                        operation.requestBody, openapi
-                    )
-                    responses = _extract_responses(operation.responses, openapi)
-
-                    route = HTTPRoute(
-                        path=path_str,
-                        method=method_upper,
-                        operation_id=operation.operationId,
-                        summary=operation.summary,
-                        description=operation.description,
-                        tags=operation.tags or [],
-                        parameters=parameters,
-                        request_body=request_body_info,
-                        responses=responses,
+                if operation and isinstance(operation, Operation_30):
+                    method_upper = cast(HttpMethod, method_lower.upper())
+                    logger.debug(f"Processing operation: {method_upper} {path_str}")
+                    try:
+                        parameters = self._extract_parameters(
+                            operation.parameters, path_level_params
+                        )
+                        request_body_info = self._extract_request_body(
+                            operation.requestBody
+                        )
+                        responses = self._extract_responses(operation.responses)
+
+                        route = HTTPRoute(
+                            path=path_str,
+                            method=method_upper,
+                            operation_id=operation.operationId,
+                            summary=operation.summary,
+                            description=operation.description,
+                            tags=operation.tags or [],
+                            parameters=parameters,
+                            request_body=request_body_info,
+                            responses=responses,
+                        )
+                        routes.append(route)
+                        logger.info(
+                            f"Successfully extracted route: {method_upper} {path_str}"
+                        )
+                    except Exception as op_error:
+                        op_id = operation.operationId or "unknown"
+                        logger.error(
+                            f"Failed to process operation {method_upper} {path_str} (ID: {op_id}): {op_error}",
+                            exc_info=True,
+                        )
+
+        logger.info(f"Finished parsing. Extracted {len(routes)} HTTP routes.")
+        return routes
+
+    def _resolve_ref(
+        self, item: Reference_30 | Schema_30 | Parameter_30 | RequestBody_30 | Any
+    ) -> Any:
+        """Resolves a potential Reference object to its target definition for OpenAPI 3.0."""
+        if isinstance(item, Reference_30):
+            ref_str = item.ref
+            try:
+                if not ref_str.startswith("#/"):
+                    raise ValueError(
+                        f"External or non-local reference not supported: {ref_str}"
                     )
-                    routes.append(route)
-                    logger.info(
-                        f"Successfully extracted route: {method_upper} {path_str}"
+                parts = ref_str.strip("#/").split("/")
+                target = self.openapi
+                for part in parts:
+                    if part.isdigit() and isinstance(target, list):
+                        target = target[int(part)]
+                    elif isinstance(target, BaseModel):
+                        # Use model_extra for fields not explicitly defined (like components types)
+                        # Check class fields first, then model_extra
+                        if part in target.__class__.model_fields:
+                            target = getattr(target, part, None)
+                        elif target.model_extra and part in target.model_extra:
+                            target = target.model_extra[part]
+                        else:
+                            # Special handling for components sub-types common structure
+                            if part == "components" and hasattr(target, "components"):
+                                target = getattr(target, "components")
+                            elif hasattr(target, part):  # Fallback check
+                                target = getattr(target, part, None)
+                            else:
+                                target = None  # Part not found
+                    elif isinstance(target, dict):
+                        target = target.get(part)
+                    else:
+                        raise ValueError(
+                            f"Cannot traverse part '{part}' in reference '{ref_str}' from type {type(target)}"
+                        )
+                    if target is None:
+                        raise ValueError(
+                            f"Reference part '{part}' not found in path '{ref_str}'"
+                        )
+                if isinstance(target, Reference_30):
+                    return self._resolve_ref(target)
+                return target
+            except (AttributeError, KeyError, IndexError, TypeError, ValueError) as e:
+                raise ValueError(f"Failed to resolve reference '{ref_str}': {e}") from e
+        return item
+
+    def _extract_schema_as_dict(
+        self, schema_obj: Schema_30 | Reference_30
+    ) -> JsonSchema:
+        """Resolves a schema/reference and returns it as a dictionary for OpenAPI 3.0."""
+        resolved_schema = self._resolve_ref(schema_obj)
+        if isinstance(resolved_schema, Schema_30):
+            # Using exclude_none=True might be better than exclude_unset sometimes
+            return resolved_schema.model_dump(
+                mode="json", by_alias=True, exclude_none=True
+            )
+        elif isinstance(resolved_schema, dict):
+            logger.warning(
+                "Resolved schema reference resulted in a dict, not a Schema model."
+            )
+            return resolved_schema
+        else:
+            ref_str = getattr(schema_obj, "ref", "unknown")
+            logger.warning(
+                f"Expected Schema after resolving ref '{ref_str}', got {type(resolved_schema)}. Returning empty dict."
+            )
+            return {}
+
+    def _extract_parameters(
+        self,
+        operation_params: list[Parameter_30 | Reference_30] | None,
+        path_item_params: list[Parameter_30 | Reference_30] | None,
+    ) -> list[ParameterInfo]:
+        """Extracts and resolves parameters for OpenAPI 3.0."""
+        extracted_params: list[ParameterInfo] = []
+        seen_params: dict[
+            tuple[str, str], bool
+        ] = {}  # Use string keys to avoid type issues
+        all_params_refs = (operation_params or []) + (path_item_params or [])
+
+        for param_or_ref in all_params_refs:
+            try:
+                parameter = cast(Parameter_30, self._resolve_ref(param_or_ref))
+                if not isinstance(parameter, Parameter_30):
+                    logger.warning(
+                        f"Expected Parameter after resolving reference, got {type(parameter)}. Skipping."
                     )
-                except Exception as op_error:
-                    op_id = operation.operationId or "unknown"
-                    logger.error(
-                        f"Failed to process operation {method_upper} {path_str} (ID: {op_id}): {op_error}",
-                        exc_info=True,
+                    continue
+
+                # OpenAPI 3.0 uses 'in' field for parameter location
+                param_in = parameter.param_in
+                param_location = self._convert_to_parameter_location(param_in)
+                param_schema_obj = parameter.param_schema
+
+                param_key = (parameter.name, param_in)
+                if param_key in seen_params:
+                    continue
+                seen_params[param_key] = True
+
+                param_schema_dict = {}
+                if param_schema_obj:  # Check if schema exists
+                    param_schema_dict = self._extract_schema_as_dict(param_schema_obj)
+                elif parameter.content:
+                    # Handle complex parameters with 'content'
+                    first_media_type = next(iter(parameter.content.values()), None)
+                    if first_media_type and first_media_type.media_type_schema:
+                        param_schema_dict = self._extract_schema_as_dict(
+                            first_media_type.media_type_schema
+                        )
+                        logger.debug(
+                            f"Parameter '{parameter.name}' using schema from 'content' field."
+                        )
+
+                # Manually create ParameterInfo instance using correct field names
+                param_info = ParameterInfo(
+                    name=parameter.name,
+                    location=param_location,  # Use converted parameter location
+                    required=parameter.required,
+                    schema=param_schema_dict,  # Populate 'schema' field in IR
+                    description=parameter.description,
+                )
+                extracted_params.append(param_info)
+
+            except (
+                ValidationError,
+                ValueError,
+                AttributeError,
+                TypeError,
+            ) as e:  # Added TypeError
+                param_name = getattr(
+                    param_or_ref, "name", getattr(param_or_ref, "ref", "unknown")
+                )
+                logger.error(
+                    f"Failed to extract parameter '{param_name}': {e}", exc_info=False
+                )
+
+        return extracted_params
+
+    def _extract_request_body(
+        self, request_body_or_ref: RequestBody_30 | Reference_30 | None
+    ) -> RequestBodyInfo | None:
+        """Extracts request body information for OpenAPI 3.0 using correct attribute names."""
+        if request_body_or_ref is None:
+            return None
+
+        try:
+            request_body = cast(RequestBody_30, self._resolve_ref(request_body_or_ref))
+
+            if not isinstance(request_body, RequestBody_30):
+                logger.warning(
+                    f"Expected RequestBody after resolving reference, got {type(request_body)}. Returning None."
+                )
+                return None
+
+            request_body_info = RequestBodyInfo(
+                required=request_body.required,
+                description=request_body.description,
+            )
+
+            # Process content field for request body schemas
+            if request_body.content:
+                for media_type_key, media_type_obj in request_body.content.items():
+                    if (
+                        media_type_obj and media_type_obj.media_type_schema
+                    ):  # CORRECTED: Use 'media_type_schema'
+                        schema_dict = self._extract_schema_as_dict(
+                            media_type_obj.media_type_schema
+                        )
+                        request_body_info.content_schema[media_type_key] = schema_dict
+
+            return request_body_info
+
+        except (ValidationError, ValueError, AttributeError) as e:
+            ref_str = getattr(request_body_or_ref, "ref", "unknown")
+            logger.error(
+                f"Failed to extract request body info from reference '{ref_str}': {e}",
+                exc_info=False,
+            )
+            return None
+
+    def _extract_responses(
+        self,
+        operation_responses: dict[str, Response_30 | Reference_30] | None,
+    ) -> dict[str, ResponseInfo]:
+        """Extracts response information from an OpenAPI 3.0 operation's responses."""
+        extracted_responses: dict[str, ResponseInfo] = {}
+        if not operation_responses:
+            return extracted_responses
+
+        for status_code, response_or_ref in operation_responses.items():
+            try:
+                # Skip 'default' response for simplicity if needed
+                # if status_code == "default":
+                #    continue
+
+                response = cast(Response_30, self._resolve_ref(response_or_ref))
+
+                if not isinstance(response, Response_30):
+                    logger.warning(
+                        f"Expected Response after resolving reference for status code {status_code}, "
+                        f"got {type(response)}. Skipping."
                     )
+                    continue
+
+                response_info = ResponseInfo(description=response.description)
+
+                # Extract content schemas if present
+                if response.content:
+                    for media_type_key, media_type_obj in response.content.items():
+                        if (
+                            media_type_obj and media_type_obj.media_type_schema
+                        ):  # CORRECTED: Use 'media_type_schema'
+                            schema_dict = self._extract_schema_as_dict(
+                                media_type_obj.media_type_schema
+                            )
+                            response_info.content_schema[media_type_key] = schema_dict
 
-    logger.info(f"Finished parsing. Extracted {len(routes)} HTTP routes.")
-    return routes
-
-
-# --- Example Usage (Optional) ---
-if __name__ == "__main__":
-    import json
-
-    logging.basicConfig(
-        level=logging.INFO, format="%(levelname)s:%(name)s:%(message)s"
-    )  # Set to INFO
-
-    petstore_schema = {
-        "openapi": "3.1.0",  # Keep corrected version
-        "info": {"title": "Simple Pet Store API", "version": "1.0.0"},
-        "paths": {
-            "/pets": {
-                "get": {
-                    "summary": "list all pets",
-                    "operationId": "listPets",
-                    "tags": ["pets"],
-                    "parameters": [
-                        {
-                            "name": "limit",
-                            "in": "query",
-                            "description": "How many items to return",
-                            "required": False,
-                            "schema": {"type": "integer", "format": "int32"},
-                        }
-                    ],
-                    "responses": {"200": {"description": "A paged array of pets"}},
-                },
-                "post": {
-                    "summary": "Create a pet",
-                    "operationId": "createPet",
-                    "tags": ["pets"],
-                    "requestBody": {"$ref": "#/components/requestBodies/PetBody"},
-                    "responses": {"201": {"description": "Null response"}},
-                },
-            },
-            "/pets/{petId}": {
-                "get": {
-                    "summary": "Info for a specific pet",
-                    "operationId": "showPetById",
-                    "tags": ["pets"],
-                    "parameters": [
-                        {
-                            "name": "petId",
-                            "in": "path",
-                            "required": True,
-                            "description": "The id of the pet",
-                            "schema": {"type": "string"},
-                        },
-                        {
-                            "name": "X-Request-ID",
-                            "in": "header",
-                            "required": False,
-                            "schema": {"type": "string", "format": "uuid"},
-                        },
-                    ],
-                    "responses": {"200": {"description": "Information about the pet"}},
-                },
-                "parameters": [  # Path level parameter example
-                    {
-                        "name": "traceId",
-                        "in": "header",
-                        "description": "Common trace ID",
-                        "required": False,
-                        "schema": {"type": "string"},
-                    }
-                ],
-            },
-        },
-        "components": {
-            "schemas": {
-                "Pet": {
-                    "type": "object",
-                    "required": ["id", "name"],
-                    "properties": {
-                        "id": {"type": "integer", "format": "int64"},
-                        "name": {"type": "string"},
-                        "tag": {"type": "string"},
-                    },
-                }
-            },
-            "requestBodies": {
-                "PetBody": {
-                    "description": "Pet object",
-                    "required": True,
-                    "content": {
-                        "application/json": {
-                            "schema": {"$ref": "#/components/schemas/Pet"}
-                        }
-                    },
-                }
-            },
-        },
-    }
+                extracted_responses[status_code] = response_info
 
-    print("--- Parsing Pet Store Schema using openapi-pydantic (Corrected) ---")
-    try:
-        http_routes = parse_openapi_to_http_routes(petstore_schema)
-        print(f"\n--- Extracted {len(http_routes)} Routes ---")
-        for i, route in enumerate(http_routes):
-            print(f"\nRoute {i + 1}:")
-            # Use model_dump for clean JSON-like output, show aliases from IR model
-            print(
-                json.dumps(route.model_dump(by_alias=True, exclude_none=True), indent=2)
-            )  # exclude_none is often cleaner
-    except ValueError as e:
-        print(f"\nError parsing schema: {e}")
-    except Exception as e:
-        print(f"\nAn unexpected error occurred: {e}")
+            except (ValidationError, ValueError, AttributeError) as e:
+                ref_str = getattr(response_or_ref, "ref", "unknown")
+                logger.error(
+                    f"Failed to extract response info for status code {status_code} "
+                    f"from reference '{ref_str}': {e}",
+                    exc_info=False,
+                )
+
+        return extracted_responses
 
 
 def clean_schema_for_display(schema: JsonSchema | None) -> JsonSchema | None: