Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Add openapi parsing utilities

Jeremiah Lowina683abb8a38f
diff --git a/src/fastmcp/utilities/openapi.py b/src/fastmcp/utilities/openapi.py
new file mode 100644
index 000000000..9b2fe599a
--- /dev/null
+++ b/src/fastmcp/utilities/openapi.py
@@ -0,0 +1,468 @@
+import logging
+from typing import Any, Dict, List, Literal, Optional, Tuple, Union, cast
+
+# Using the recommended library: openapi-pydantic
+from openapi_pydantic import (
+ MediaType,
+ OpenAPI,
+ Operation,
+ Parameter,
+ PathItem,
+ Reference,
+ RequestBody,
+ Schema,
+)
+from pydantic import BaseModel, Field, ValidationError
+
+logger = logging.getLogger(__name__)
+
+# --- Intermediate Representation (IR) Definition ---
+# (IR models remain the same)
+
+HttpMethod = Literal[
+ "GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD", "TRACE"
+]
+ParameterLocation = Literal["path", "query", "header", "cookie"]
+JsonSchema = Dict[str, Any]
+
+
+class ParameterInfo(BaseModel):
+ """Represents a single parameter for an HTTP operation in our IR."""
+
+ name: str
+ location: ParameterLocation # Mapped from 'in' field of openapi-pydantic Parameter
+ required: bool = False
+ schema_: JsonSchema = Field(..., alias="schema") # Target name in IR
+ description: Optional[str] = None
+
+ # No model_config needed here if we populate manually after accessing 'in'
+
+
+class RequestBodyInfo(BaseModel):
+ """Represents the request body for an HTTP operation in our IR."""
+
+ required: bool = False
+ content_schema: Dict[str, JsonSchema] = Field(
+ default_factory=dict
+ ) # Key: media type
+ description: Optional[str] = None
+
+
+class HTTPRoute(BaseModel):
+ """Intermediate Representation for a single OpenAPI operation."""
+
+ path: str
+ method: HttpMethod
+ operation_id: Optional[str] = None
+ summary: Optional[str] = None
+ description: Optional[str] = None
+ tags: List[str] = Field(default_factory=list)
+ parameters: List[ParameterInfo] = Field(default_factory=list)
+ request_body: Optional[RequestBodyInfo] = None
+
+
+# --- Helper Functions ---
+
+
+def _resolve_ref(
+ item: Union[Reference, Schema, Parameter, RequestBody, Any], openapi: OpenAPI
+) -> Any:
+ """Resolves a potential Reference object to its target definition (no changes needed here)."""
+ 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 = 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.model_fields: # Access class attribute here
+ 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 _resolve_ref(target, openapi)
+ 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(
+ schema_obj: Union[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: Optional[List[Union[Parameter, Reference]]],
+ path_item_params: Optional[List[Union[Parameter, Reference]]],
+ 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'
+ # --- *** ---
+
+ 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."
+ )
+
+ # 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(
+ request_body_or_ref: Optional[Union[RequestBody, Reference]], openapi: OpenAPI
+) -> Optional[RequestBodyInfo]:
+ """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
+
+ 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'
+ # --- *** ---
+ try:
+ # Use the corrected attribute here as well
+ schema_dict = _extract_schema_as_dict(
+ media_type_obj.media_type_schema, openapi
+ )
+ 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 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."
+ )
+
+ 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
+
+
+# --- 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 []
+
+ 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",
+ ]:
+ continue
+
+ operation: Optional[Operation] = 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
+ )
+
+ 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,
+ )
+ 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
+
+
+# --- 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"}
+ }
+ },
+ }
+ },
+ },
+ }
+
+ 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}")
diff --git a/tests/utilities/__init__.py b/tests/utilities/__init__.py
new file mode 100644
index 000000000..e17939203
--- /dev/null
+++ b/tests/utilities/__init__.py
@@ -0,0 +1 @@
+"""Tests for utilities in the fastmcp package."""
diff --git a/tests/utilities/openapi/__init__.py b/tests/utilities/openapi/__init__.py
new file mode 100644
index 000000000..0be677d94
--- /dev/null
+++ b/tests/utilities/openapi/__init__.py
@@ -0,0 +1 @@
+"""Tests for the OpenAPI utilities."""
diff --git a/tests/utilities/openapi/conftest.py b/tests/utilities/openapi/conftest.py
new file mode 100644
index 000000000..8b1378917
--- /dev/null
+++ b/tests/utilities/openapi/conftest.py
@@ -0,0 +1 @@
+
diff --git a/tests/utilities/openapi/test_openapi.py b/tests/utilities/openapi/test_openapi.py
new file mode 100644
index 000000000..0505b5e12
--- /dev/null
+++ b/tests/utilities/openapi/test_openapi.py
@@ -0,0 +1,709 @@
+"""Tests for the OpenAPI parsing utilities."""
+
+from typing import Any, Dict
+
+import pytest
+from fastapi import Body, FastAPI, Path, Query
+from pydantic import BaseModel, Field
+
+from fastmcp.utilities.openapi import parse_openapi_to_http_routes
+
+# --- Test Data: Static OpenAPI Schema Dictionaries --- #
+
+
+def petstore_schema() -> Dict[str, Any]:
+ """Fixture that returns a simple Pet Store API schema."""
+ return {
+ "openapi": "3.1.0",
+ "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"}
+ }
+ },
+ }
+ },
+ },
+ }
+
+
+def parsed_petstore_routes(petstore_schema):
+ """Return parsed routes from the PetStore schema."""
+ return parse_openapi_to_http_routes(petstore_schema)
+
+
+def bookstore_schema() -> Dict[str, Any]:
+ """Fixture that returns a Book Store API schema with different parameter types."""
+ return {
+ "openapi": "3.1.0",
+ "info": {"title": "Book Store API", "version": "1.0.0"},
+ "paths": {
+ "/books": {
+ "get": {
+ "summary": "List all books",
+ "operationId": "listBooks",
+ "tags": ["books"],
+ "parameters": [
+ {
+ "name": "genre",
+ "in": "query",
+ "description": "Filter by genre",
+ "required": False,
+ "schema": {"type": "string"},
+ },
+ {
+ "name": "published_after",
+ "in": "query",
+ "description": "Filter by publication date",
+ "required": False,
+ "schema": {"type": "string", "format": "date"},
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "Maximum number of results",
+ "required": False,
+ "schema": {"type": "integer", "default": 10},
+ },
+ ],
+ "responses": {"200": {"description": "A list of books"}},
+ },
+ "post": {
+ "summary": "Create a new book",
+ "operationId": "createBook",
+ "tags": ["books"],
+ "requestBody": {
+ "required": True,
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "required": ["title", "author"],
+ "properties": {
+ "title": {"type": "string"},
+ "author": {"type": "string"},
+ "isbn": {"type": "string"},
+ "published": {
+ "type": "string",
+ "format": "date",
+ },
+ "genre": {"type": "string"},
+ },
+ }
+ }
+ },
+ },
+ "responses": {"201": {"description": "Book created"}},
+ },
+ },
+ "/books/{isbn}": {
+ "get": {
+ "summary": "Get book by ISBN",
+ "operationId": "getBook",
+ "tags": ["books"],
+ "parameters": [
+ {
+ "name": "isbn",
+ "in": "path",
+ "required": True,
+ "description": "ISBN of the book",
+ "schema": {"type": "string"},
+ }
+ ],
+ "responses": {"200": {"description": "Book details"}},
+ },
+ "delete": {
+ "summary": "Delete a book",
+ "operationId": "deleteBook",
+ "tags": ["books"],
+ "parameters": [
+ {
+ "name": "isbn",
+ "in": "path",
+ "required": True,
+ "description": "ISBN of the book to delete",
+ "schema": {"type": "string"},
+ }
+ ],
+ "responses": {"204": {"description": "Book deleted"}},
+ },
+ },
+ },
+ }
+
+
+def parsed_bookstore_routes(bookstore_schema):
+ """Return parsed routes from the BookStore schema."""
+ return parse_openapi_to_http_routes(bookstore_schema)
+
+
+# --- FastAPI App Fixtures --- #
+
+
+class Item(BaseModel):
+ """Example pydantic model for API testing."""
+
+ name: str
+ description: str | None = None
+ price: float
+ tax: float | None = None
+ tags: list[str] = Field(default_factory=list)
+
+
+def fastapi_app() -> FastAPI:
+ """Fixture that returns a FastAPI app with various types of endpoints."""
+ app = FastAPI(title="Test API", version="1.0.0")
+
+ @app.get("/items/", operation_id="list_items")
+ async def list_items(skip: int = 0, limit: int = 10):
+ """List all items with pagination."""
+ return [
+ {"name": f"Item {i}", "price": float(i)} for i in range(skip, skip + limit)
+ ]
+
+ @app.post("/items/", operation_id="create_item")
+ async def create_item(item: Item):
+ """Create a new item."""
+ return item
+
+ @app.get("/items/{item_id}", operation_id="get_item")
+ async def get_item(
+ item_id: int = Path(..., description="The ID of the item to get"),
+ q: str | None = Query(None, description="Optional query string"),
+ ):
+ """Get an item by ID."""
+ return {"item_id": item_id, "q": q}
+
+ @app.put("/items/{item_id}", operation_id="update_item")
+ async def update_item(
+ item_id: int = Path(..., description="The ID of the item to update"),
+ item: Item = Body(..., description="The updated item data"),
+ ):
+ """Update an existing item."""
+ return {"item_id": item_id, **item.model_dump()}
+
+ @app.delete("/items/{item_id}", operation_id="delete_item")
+ async def delete_item(
+ item_id: int = Path(..., description="The ID of the item to delete"),
+ ):
+ """Delete an item by ID."""
+ return {"item_id": item_id, "deleted": True}
+
+ @app.get("/items/{item_id}/tags/{tag_id}", operation_id="get_item_tag")
+ async def get_item_tag(
+ item_id: int = Path(..., description="The ID of the item"),
+ tag_id: str = Path(..., description="The ID of the tag"),
+ ):
+ """Get a specific tag for an item."""
+ return {"item_id": item_id, "tag_id": tag_id}
+
+ @app.post("/upload/", operation_id="upload_file")
+ async def upload_file(
+ file_name: str = Query(..., description="Name of the file to upload"),
+ content_type: str = Query(..., description="Content type of the file"),
+ ):
+ """Upload a file (dummy endpoint for testing query params with POST)."""
+ return {
+ "file_name": file_name,
+ "content_type": content_type,
+ "status": "uploaded",
+ }
+
+ return app
+
+
+def fastapi_openapi_schema(fastapi_app) -> Dict[str, Any]:
+ """Fixture that returns the OpenAPI schema of the FastAPI app."""
+ return fastapi_app.openapi()
+
+
+def parsed_fastapi_routes(fastapi_openapi_schema):
+ """Return parsed routes from a FastAPI OpenAPI schema."""
+ return parse_openapi_to_http_routes(fastapi_openapi_schema)
+
+
+def fastapi_route_map(parsed_fastapi_routes):
+ """Return a dictionary of routes by operation ID."""
+ return {
+ r.operation_id: r for r in parsed_fastapi_routes if r.operation_id is not None
+ }
+
+
+# --- Tests for PetStore schema --- #
+
+
+def test_petstore_route_count(parsed_petstore_routes):
+ """Test that parsing the PetStore schema correctly identifies the number of routes."""
+ assert len(parsed_petstore_routes) == 3
+
+
+def test_petstore_get_pets_operation_id(parsed_petstore_routes):
+ """Test that GET /pets operation_id is correctly parsed."""
+ get_pets = next(
+ (r for r in parsed_petstore_routes if r.method == "GET" and r.path == "/pets"),
+ None,
+ )
+ assert get_pets is not None
+ assert get_pets.operation_id == "listPets"
+
+
+def test_petstore_query_parameter(parsed_petstore_routes):
+ """Test that query parameter 'limit' is correctly parsed from the schema."""
+ get_pets = next(
+ (r for r in parsed_petstore_routes if r.method == "GET" and r.path == "/pets"),
+ None,
+ )
+
+ assert get_pets is not None
+ assert len(get_pets.parameters) == 1
+ param = get_pets.parameters[0]
+ assert param.name == "limit"
+ assert param.location == "query"
+ assert param.required is False
+ assert param.schema_.get("type") == "integer"
+ assert param.schema_.get("format") == "int32"
+
+
+def test_petstore_path_parameter(parsed_petstore_routes):
+ """Test that path parameter 'petId' is correctly parsed from the schema."""
+ get_pet = next(
+ (
+ r
+ for r in parsed_petstore_routes
+ if r.method == "GET" and r.path == "/pets/{petId}"
+ ),
+ None,
+ )
+
+ assert get_pet is not None
+ path_param = next((p for p in get_pet.parameters if p.name == "petId"), None)
+ assert path_param is not None
+ assert path_param.location == "path"
+ assert path_param.required is True
+ assert path_param.schema_.get("type") == "string"
+
+
+def test_petstore_header_parameters(parsed_petstore_routes):
+ """Test that header parameters are correctly parsed from the schema."""
+ get_pet = next(
+ (
+ r
+ for r in parsed_petstore_routes
+ if r.method == "GET" and r.path == "/pets/{petId}"
+ ),
+ None,
+ )
+
+ assert get_pet is not None
+ header_params = [p for p in get_pet.parameters if p.location == "header"]
+ assert len(header_params) == 2
+
+
+def test_petstore_header_parameter_names(parsed_petstore_routes):
+ """Test that header parameter names are correctly parsed."""
+ get_pet = next(
+ (
+ r
+ for r in parsed_petstore_routes
+ if r.method == "GET" and r.path == "/pets/{petId}"
+ ),
+ None,
+ )
+
+ assert get_pet is not None
+ header_params = [p for p in get_pet.parameters if p.location == "header"]
+ header_names = [p.name for p in header_params]
+ assert "X-Request-ID" in header_names
+ assert "traceId" in header_names
+
+
+def test_petstore_path_level_parameters(parsed_petstore_routes):
+ """Test that path-level parameters are correctly merged into the operation."""
+ get_pet = next(
+ (
+ r
+ for r in parsed_petstore_routes
+ if r.method == "GET" and r.path == "/pets/{petId}"
+ ),
+ None,
+ )
+
+ assert get_pet is not None
+ trace_param = next((p for p in get_pet.parameters if p.name == "traceId"), None)
+ assert trace_param is not None
+ assert trace_param.location == "header"
+ assert trace_param.required is False
+
+
+def test_petstore_request_body_reference_resolution(parsed_petstore_routes):
+ """Test that request body references are correctly resolved."""
+ create_pet = next(
+ (r for r in parsed_petstore_routes if r.method == "POST" and r.path == "/pets"),
+ None,
+ )
+
+ assert create_pet is not None
+ assert create_pet.request_body is not None
+ assert create_pet.request_body.required is True
+ assert "application/json" in create_pet.request_body.content_schema
+
+
+def test_petstore_schema_reference_resolution(parsed_petstore_routes):
+ """Test that schema references in request bodies are correctly resolved."""
+ create_pet = next(
+ (r for r in parsed_petstore_routes if r.method == "POST" and r.path == "/pets"),
+ None,
+ )
+
+ assert create_pet is not None
+ assert create_pet.request_body is not None
+ json_schema = create_pet.request_body.content_schema["application/json"]
+ properties = json_schema.get("properties", {})
+
+ assert "id" in properties
+ assert "name" in properties
+ assert "tag" in properties
+
+
+def test_petstore_required_fields_resolution(parsed_petstore_routes):
+ """Test that required fields are correctly resolved from referenced schemas."""
+ create_pet = next(
+ (r for r in parsed_petstore_routes if r.method == "POST" and r.path == "/pets"),
+ None,
+ )
+
+ assert create_pet is not None
+ assert create_pet.request_body is not None
+ json_schema = create_pet.request_body.content_schema["application/json"]
+ assert json_schema.get("required") == ["id", "name"]
+
+
+# --- Tests for BookStore schema --- #
+
+
+def test_bookstore_route_count(parsed_bookstore_routes):
+ """Test that parsing the BookStore schema correctly identifies the number of routes."""
+ assert len(parsed_bookstore_routes) == 4
+
+
+def test_bookstore_query_parameter_count(parsed_bookstore_routes):
+ """Test that the correct number of query parameters are parsed."""
+ list_books = next(
+ (r for r in parsed_bookstore_routes if r.operation_id == "listBooks"), None
+ )
+
+ assert list_books is not None
+ assert len(list_books.parameters) == 3
+
+
+def test_bookstore_query_parameter_names(parsed_bookstore_routes):
+ """Test that query parameter names are correctly parsed."""
+ list_books = next(
+ (r for r in parsed_bookstore_routes if r.operation_id == "listBooks"), None
+ )
+
+ assert list_books is not None
+ param_map = {p.name: p for p in list_books.parameters}
+ assert "genre" in param_map
+ assert "published_after" in param_map
+ assert "limit" in param_map
+
+
+def test_bookstore_query_parameter_formats(parsed_bookstore_routes):
+ """Test that query parameter formats are correctly parsed."""
+ list_books = next(
+ (r for r in parsed_bookstore_routes if r.operation_id == "listBooks"), None
+ )
+
+ assert list_books is not None
+ param_map = {p.name: p for p in list_books.parameters}
+ assert param_map["published_after"].schema_.get("format") == "date"
+
+
+def test_bookstore_query_parameter_defaults(parsed_bookstore_routes):
+ """Test that query parameter default values are correctly parsed."""
+ list_books = next(
+ (r for r in parsed_bookstore_routes if r.operation_id == "listBooks"), None
+ )
+
+ assert list_books is not None
+ param_map = {p.name: p for p in list_books.parameters}
+ assert param_map["limit"].schema_.get("default") == 10
+
+
+def test_bookstore_inline_request_body_presence(parsed_bookstore_routes):
+ """Test that request bodies with inline schemas are present."""
+ create_book = next(
+ (r for r in parsed_bookstore_routes if r.operation_id == "createBook"), None
+ )
+
+ assert create_book is not None
+ assert create_book.request_body is not None
+ assert create_book.request_body.required is True
+ assert "application/json" in create_book.request_body.content_schema
+
+
+def test_bookstore_inline_request_body_properties(parsed_bookstore_routes):
+ """Test that request body properties are correctly parsed from inline schemas."""
+ create_book = next(
+ (r for r in parsed_bookstore_routes if r.operation_id == "createBook"), None
+ )
+
+ assert create_book is not None
+ assert create_book.request_body is not None
+
+ json_schema = create_book.request_body.content_schema["application/json"]
+ properties = json_schema.get("properties", {})
+
+ assert "title" in properties
+ assert "author" in properties
+ assert "isbn" in properties
+ assert "published" in properties
+ assert "genre" in properties
+
+
+def test_bookstore_inline_request_body_required_fields(parsed_bookstore_routes):
+ """Test that required fields in inline schema are correctly parsed."""
+ create_book = next(
+ (r for r in parsed_bookstore_routes if r.operation_id == "createBook"), None
+ )
+
+ assert create_book is not None
+ assert create_book.request_body is not None
+
+ json_schema = create_book.request_body.content_schema["application/json"]
+ assert json_schema.get("required") == ["title", "author"]
+
+
+def test_bookstore_delete_method(parsed_bookstore_routes):
+ """Test that DELETE method is correctly parsed from the schema."""
+ delete_book = next(
+ (r for r in parsed_bookstore_routes if r.method == "DELETE"), None
+ )
+
+ assert delete_book is not None
+ assert delete_book.operation_id == "deleteBook"
+ assert delete_book.path == "/books/{isbn}"
+
+
+def test_bookstore_delete_method_parameters(parsed_bookstore_routes):
+ """Test that parameters for DELETE method are correctly parsed."""
+ delete_book = next(
+ (r for r in parsed_bookstore_routes if r.method == "DELETE"), None
+ )
+
+ assert delete_book is not None
+ assert len(delete_book.parameters) == 1
+ assert delete_book.parameters[0].name == "isbn"
+
+
+# --- Tests for FastAPI Generated Schema --- #
+
+
+def test_fastapi_route_count(parsed_fastapi_routes):
+ """Test that parsing a FastAPI-generated schema correctly identifies the number of routes."""
+ assert len(parsed_fastapi_routes) == 7
+
+
+def test_fastapi_parameter_default_values(fastapi_route_map):
+ """Test that default parameter values are correctly parsed from the schema."""
+ list_items = fastapi_route_map["list_items"]
+
+ param_map = {p.name: p for p in list_items.parameters}
+ assert "skip" in param_map
+ assert "limit" in param_map
+
+
+def test_fastapi_skip_parameter_default(fastapi_route_map):
+ """Test that skip parameter default value is correctly parsed."""
+ list_items = fastapi_route_map["list_items"]
+
+ param_map = {p.name: p for p in list_items.parameters}
+ assert param_map["skip"].schema_.get("default") == 0
+
+
+def test_fastapi_limit_parameter_default(fastapi_route_map):
+ """Test that limit parameter default value is correctly parsed."""
+ list_items = fastapi_route_map["list_items"]
+
+ param_map = {p.name: p for p in list_items.parameters}
+ assert param_map["limit"].schema_.get("default") == 10
+
+
+def test_fastapi_request_body_from_pydantic(fastapi_route_map):
+ """Test that request bodies from Pydantic models are present."""
+ create_item = fastapi_route_map["create_item"]
+
+ assert create_item.request_body is not None
+ assert "application/json" in create_item.request_body.content_schema
+
+
+def test_fastapi_request_body_properties(fastapi_route_map):
+ """Test that request body properties from Pydantic models are correctly parsed."""
+ create_item = fastapi_route_map["create_item"]
+
+ json_schema = create_item.request_body.content_schema["application/json"]
+ properties = json_schema.get("properties", {})
+
+ assert "name" in properties
+ assert "description" in properties
+ assert "price" in properties
+ assert "tax" in properties
+ assert "tags" in properties
+
+
+def test_fastapi_request_body_required_fields(fastapi_route_map):
+ """Test that required fields from Pydantic models are correctly parsed."""
+ create_item = fastapi_route_map["create_item"]
+
+ json_schema = create_item.request_body.content_schema["application/json"]
+ required = json_schema.get("required", [])
+
+ assert "name" in required
+ assert "price" in required
+
+
+def test_fastapi_path_parameter_presence(fastapi_route_map):
+ """Test that path parameters are present in FastAPI schema."""
+ get_item = fastapi_route_map["get_item"]
+
+ path_params = [p for p in get_item.parameters if p.location == "path"]
+ assert len(path_params) == 1
+
+
+def test_fastapi_path_parameter_properties(fastapi_route_map):
+ """Test that path parameters properties are correctly parsed."""
+ get_item = fastapi_route_map["get_item"]
+
+ path_params = [p for p in get_item.parameters if p.location == "path"]
+ assert path_params[0].name == "item_id"
+ assert path_params[0].required is True
+
+
+def test_fastapi_optional_query_parameter(fastapi_route_map):
+ """Test that optional query parameters are correctly parsed."""
+ get_item = fastapi_route_map["get_item"]
+
+ query_params = [p for p in get_item.parameters if p.location == "query"]
+ assert len(query_params) == 1
+ assert query_params[0].name == "q"
+ assert query_params[0].required is False
+
+
+def test_fastapi_multiple_path_parameter_count(fastapi_route_map):
+ """Test that multiple path parameters count is correct."""
+ get_item_tag = fastapi_route_map["get_item_tag"]
+
+ path_params = [p for p in get_item_tag.parameters if p.location == "path"]
+ assert len(path_params) == 2
+
+
+def test_fastapi_multiple_path_parameter_names(fastapi_route_map):
+ """Test that multiple path parameter names are correctly parsed."""
+ get_item_tag = fastapi_route_map["get_item_tag"]
+
+ path_params = [p for p in get_item_tag.parameters if p.location == "path"]
+ param_names = [p.name for p in path_params]
+ assert "item_id" in param_names
+ assert "tag_id" in param_names
+
+
+def test_fastapi_post_with_query_parameters(fastapi_route_map):
+ """Test that query parameters for POST methods are correctly parsed."""
+ upload_file = fastapi_route_map["upload_file"]
+
+ assert upload_file.method == "POST"
+ query_params = [p for p in upload_file.parameters if p.location == "query"]
+ assert len(query_params) == 2
+
+
+def test_fastapi_post_query_parameter_names(fastapi_route_map):
+ """Test that query parameter names for POST methods are correctly parsed."""
+ upload_file = fastapi_route_map["upload_file"]
+
+ query_params = [p for p in upload_file.parameters if p.location == "query"]
+ param_names = [p.name for p in query_params]
+ assert "file_name" in param_names
+ assert "content_type" in param_names
diff --git a/tests/utilities/openapi/test_openapi_advanced.py b/tests/utilities/openapi/test_openapi_advanced.py
new file mode 100644
index 000000000..bacb5fbbd
--- /dev/null
+++ b/tests/utilities/openapi/test_openapi_advanced.py
@@ -0,0 +1,594 @@
+"""Tests for advanced features of the OpenAPI utilities."""
+
+from typing import Any, Dict
+
+import pytest
+
+from fastmcp.utilities.openapi import parse_openapi_to_http_routes
+
+
+def complex_schema() -> Dict[str, Any]:
+ """Fixture that returns a complex OpenAPI schema with nested references."""
+ return {
+ "openapi": "3.1.0",
+ "info": {"title": "Complex API", "version": "1.0.0"},
+ "paths": {
+ "/users": {
+ "get": {
+ "summary": "List all users",
+ "operationId": "listUsers",
+ "parameters": [
+ {"$ref": "#/components/parameters/PageLimit"},
+ {"$ref": "#/components/parameters/PageOffset"},
+ ],
+ "responses": {"200": {"description": "A list of users"}},
+ }
+ },
+ "/users/{userId}": {
+ "get": {
+ "summary": "Get user by ID",
+ "operationId": "getUser",
+ "parameters": [
+ {"$ref": "#/components/parameters/UserId"},
+ {"$ref": "#/components/parameters/IncludeInactive"},
+ ],
+ "responses": {"200": {"description": "User details"}},
+ }
+ },
+ "/users/{userId}/orders": {
+ "post": {
+ "summary": "Create order for user",
+ "operationId": "createOrder",
+ "parameters": [{"$ref": "#/components/parameters/UserId"}],
+ "requestBody": {"$ref": "#/components/requestBodies/OrderRequest"},
+ "responses": {"201": {"description": "Order created"}},
+ }
+ },
+ },
+ "components": {
+ "parameters": {
+ "UserId": {
+ "name": "userId",
+ "in": "path",
+ "required": True,
+ "schema": {"type": "string", "format": "uuid"},
+ },
+ "PageLimit": {
+ "name": "limit",
+ "in": "query",
+ "schema": {"type": "integer", "default": 20, "maximum": 100},
+ },
+ "PageOffset": {
+ "name": "offset",
+ "in": "query",
+ "schema": {"type": "integer", "default": 0},
+ },
+ "IncludeInactive": {
+ "name": "include_inactive",
+ "in": "query",
+ "schema": {"type": "boolean", "default": False},
+ },
+ },
+ "schemas": {
+ "User": {
+ "type": "object",
+ "properties": {
+ "id": {"type": "string", "format": "uuid"},
+ "name": {"type": "string"},
+ "email": {"type": "string", "format": "email"},
+ "role": {"$ref": "#/components/schemas/Role"},
+ "address": {"$ref": "#/components/schemas/Address"},
+ },
+ },
+ "Role": {
+ "type": "string",
+ "enum": ["admin", "user", "guest"],
+ },
+ "Address": {
+ "type": "object",
+ "properties": {
+ "street": {"type": "string"},
+ "city": {"type": "string"},
+ "zip": {"type": "string"},
+ "country": {"type": "string"},
+ },
+ },
+ "Order": {
+ "type": "object",
+ "properties": {
+ "id": {"type": "string", "format": "uuid"},
+ "items": {
+ "type": "array",
+ "items": {"$ref": "#/components/schemas/OrderItem"},
+ },
+ "total": {"type": "number"},
+ "status": {"$ref": "#/components/schemas/OrderStatus"},
+ },
+ },
+ "OrderItem": {
+ "type": "object",
+ "properties": {
+ "product_id": {"type": "string", "format": "uuid"},
+ "quantity": {"type": "integer"},
+ "price": {"type": "number"},
+ },
+ },
+ "OrderStatus": {
+ "type": "string",
+ "enum": [
+ "pending",
+ "processing",
+ "shipped",
+ "delivered",
+ "cancelled",
+ ],
+ },
+ },
+ "requestBodies": {
+ "OrderRequest": {
+ "description": "Order to create",
+ "required": True,
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "required": ["items"],
+ "properties": {
+ "items": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/OrderItem"
+ },
+ },
+ "notes": {"type": "string"},
+ },
+ }
+ }
+ },
+ }
+ },
+ },
+ }
+
+
+def parsed_complex_routes(complex_schema):
+ """Return parsed routes from the complex schema."""
+ return parse_openapi_to_http_routes(complex_schema)
+
+
+def complex_route_map(parsed_complex_routes):
+ """Return a dictionary of routes by operation ID."""
+ return {
+ r.operation_id: r for r in parsed_complex_routes if r.operation_id is not None
+ }
+
+
+def schema_with_invalid_reference() -> Dict[str, Any]:
+ """Fixture that returns a schema with an invalid reference."""
+ return {
+ "openapi": "3.1.0",
+ "info": {"title": "Invalid Reference API", "version": "1.0.0"},
+ "paths": {
+ "/broken-ref": {
+ "get": {
+ "summary": "Endpoint with broken reference",
+ "operationId": "brokenRef",
+ "parameters": [
+ {"$ref": "#/components/parameters/NonExistentParam"}
+ ],
+ "responses": {"200": {"description": "Something"}},
+ }
+ }
+ },
+ "components": {
+ "parameters": {} # Empty parameters object to ensure the reference is broken
+ },
+ }
+
+
+def schema_with_content_params() -> Dict[str, Any]:
+ """Fixture that returns a schema with content-based parameters (complex parameters)."""
+ return {
+ "openapi": "3.1.0",
+ "info": {"title": "Content Params API", "version": "1.0.0"},
+ "paths": {
+ "/complex-params": {
+ "post": {
+ "summary": "Endpoint with complex parameter",
+ "operationId": "complexParams",
+ "parameters": [
+ {
+ "name": "filter",
+ "in": "query",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "field": {"type": "string"},
+ "operator": {
+ "type": "string",
+ "enum": ["eq", "gt", "lt"],
+ },
+ "value": {"type": "string"},
+ },
+ }
+ }
+ },
+ }
+ ],
+ "responses": {"200": {"description": "Results"}},
+ }
+ },
+ },
+ }
+
+
+def parsed_content_param_routes(schema_with_content_params):
+ """Return parsed routes from the schema with content parameters."""
+ return parse_openapi_to_http_routes(schema_with_content_params)
+
+
+def schema_all_http_methods() -> Dict[str, Any]:
+ """Fixture that returns a schema with all HTTP methods."""
+ return {
+ "openapi": "3.1.0",
+ "info": {"title": "All Methods API", "version": "1.0.0"},
+ "paths": {
+ "/resource": {
+ "get": {
+ "operationId": "getResource",
+ "responses": {"200": {"description": "Success"}},
+ },
+ "post": {
+ "operationId": "createResource",
+ "responses": {"201": {"description": "Created"}},
+ },
+ "put": {
+ "operationId": "updateResource",
+ "responses": {"200": {"description": "Updated"}},
+ },
+ "delete": {
+ "operationId": "deleteResource",
+ "responses": {"204": {"description": "Deleted"}},
+ },
+ "patch": {
+ "operationId": "patchResource",
+ "responses": {"200": {"description": "Patched"}},
+ },
+ "head": {
+ "operationId": "headResource",
+ "responses": {"200": {"description": "Headers only"}},
+ },
+ "options": {
+ "operationId": "optionsResource",
+ "responses": {"200": {"description": "Options"}},
+ },
+ "trace": {
+ "operationId": "traceResource",
+ "responses": {"200": {"description": "Trace"}},
+ },
+ },
+ },
+ }
+
+
+def parsed_http_methods_routes(schema_all_http_methods):
+ """Return parsed routes from the schema with all HTTP methods."""
+ return parse_openapi_to_http_routes(schema_all_http_methods)
+
+
+# --- Tests for complex schemas with references --- #
+
+
+def test_complex_schema_route_count(parsed_complex_routes):
+ """Test that parsing a schema with references successfully extracts all routes."""
+ assert len(parsed_complex_routes) == 3
+
+
+def test_complex_schema_list_users_query_param_limit(complex_route_map):
+ """Test that a reference to a limit query parameter is correctly resolved."""
+ list_users = complex_route_map["listUsers"]
+
+ limit_param = next((p for p in list_users.parameters if p.name == "limit"), None)
+ assert limit_param is not None
+ assert limit_param.location == "query"
+ assert limit_param.schema_.get("default") == 20
+
+
+def test_complex_schema_list_users_query_param_limit_maximum(complex_route_map):
+ """Test that a limit parameter's maximum value is correctly resolved."""
+ list_users = complex_route_map["listUsers"]
+
+ limit_param = next((p for p in list_users.parameters if p.name == "limit"), None)
+ assert limit_param is not None
+ assert limit_param.schema_.get("maximum") == 100
+
+
+def test_complex_schema_get_user_path_param_existence(complex_route_map):
+ """Test that a reference to a path parameter exists."""
+ get_user = complex_route_map["getUser"]
+
+ user_id_param = next((p for p in get_user.parameters if p.name == "userId"), None)
+ assert user_id_param is not None
+ assert user_id_param.location == "path"
+
+
+def test_complex_schema_get_user_path_param_required(complex_route_map):
+ """Test that a path parameter is correctly marked as required."""
+ get_user = complex_route_map["getUser"]
+
+ user_id_param = next((p for p in get_user.parameters if p.name == "userId"), None)
+ assert user_id_param is not None
+ assert user_id_param.required is True
+
+
+def test_complex_schema_get_user_path_param_format(complex_route_map):
+ """Test that a path parameter format is correctly resolved."""
+ get_user = complex_route_map["getUser"]
+
+ user_id_param = next((p for p in get_user.parameters if p.name == "userId"), None)
+ assert user_id_param is not None
+ assert user_id_param.schema_.get("format") == "uuid"
+
+
+def test_complex_schema_create_order_request_body_presence(complex_route_map):
+ """Test that a reference to a request body is resolved correctly."""
+ create_order = complex_route_map["createOrder"]
+
+ assert create_order.request_body is not None
+ assert create_order.request_body.required is True
+
+
+def test_complex_schema_create_order_request_body_content_type(complex_route_map):
+ """Test that request body content type is correctly resolved."""
+ create_order = complex_route_map["createOrder"]
+
+ assert create_order.request_body is not None
+ assert "application/json" in create_order.request_body.content_schema
+
+
+def test_complex_schema_create_order_request_body_properties(complex_route_map):
+ """Test that request body properties are correctly resolved."""
+ create_order = complex_route_map["createOrder"]
+
+ assert create_order.request_body is not None
+ json_schema = create_order.request_body.content_schema["application/json"]
+ assert "items" in json_schema.get("properties", {})
+
+
+def test_complex_schema_create_order_request_body_required_fields(complex_route_map):
+ """Test that request body required fields are correctly resolved."""
+ create_order = complex_route_map["createOrder"]
+
+ assert create_order.request_body is not None
+ json_schema = create_order.request_body.content_schema["application/json"]
+ assert json_schema.get("required") == ["items"]
+
+
+# --- Tests for schema reference resolution errors --- #
+
+
+def test_parser_handles_broken_references(schema_with_invalid_reference):
+ """Test that parser handles broken references gracefully."""
+ # We're just checking that the function doesn't throw an exception
+ routes = parse_openapi_to_http_routes(schema_with_invalid_reference)
+
+ # Should still return routes list (may be empty)
+ assert isinstance(routes, list)
+
+ # Verify that the route with broken parameter reference is still included
+ # though it may not have the parameter properly
+ broken_route = next(
+ (r for r in routes if r.path == "/broken-ref" and r.method == "GET"), None
+ )
+
+ # The route should still be present
+ assert broken_route is not None
+ assert broken_route.operation_id == "brokenRef"
+
+
+# --- Tests for content-based parameters --- #
+
+
+def test_content_param_parameter_name(parsed_content_param_routes):
+ """Test that parser correctly extracts name for content-based parameters."""
+ complex_params = parsed_content_param_routes[0]
+
+ assert len(complex_params.parameters) == 1
+ param = complex_params.parameters[0]
+ assert param.name == "filter"
+
+
+def test_content_param_parameter_location(parsed_content_param_routes):
+ """Test that parser correctly extracts location for content-based parameters."""
+ complex_params = parsed_content_param_routes[0]
+
+ assert len(complex_params.parameters) == 1
+ param = complex_params.parameters[0]
+ assert param.location == "query"
+
+
+def test_content_param_schema_properties_presence(parsed_content_param_routes):
+ """Test that parser extracts schema properties from content-based parameter."""
+ complex_params = parsed_content_param_routes[0]
+
+ param = complex_params.parameters[0]
+ properties = param.schema_.get("properties", {})
+
+ assert "field" in properties
+ assert "operator" in properties
+ assert "value" in properties
+
+
+def test_content_param_schema_enum_presence(parsed_content_param_routes):
+ """Test that parser extracts enum values from content-based parameter."""
+ complex_params = parsed_content_param_routes[0]
+
+ param = complex_params.parameters[0]
+ properties = param.schema_.get("properties", {})
+
+ assert "enum" in properties.get("operator", {})
+
+
+# --- Tests for HTTP methods --- #
+
+
+def test_http_get_method_presence(parsed_http_methods_routes):
+ """Test that GET method is correctly extracted."""
+ get_route = next((r for r in parsed_http_methods_routes if r.method == "GET"), None)
+
+ assert get_route is not None
+ assert get_route.operation_id == "getResource"
+
+
+def test_http_get_method_path(parsed_http_methods_routes):
+ """Test that GET method path is correctly extracted."""
+ get_route = next((r for r in parsed_http_methods_routes if r.method == "GET"), None)
+
+ assert get_route is not None
+ assert get_route.path == "/resource"
+
+
+def test_http_post_method_presence(parsed_http_methods_routes):
+ """Test that POST method is correctly extracted."""
+ post_route = next(
+ (r for r in parsed_http_methods_routes if r.method == "POST"), None
+ )
+
+ assert post_route is not None
+ assert post_route.operation_id == "createResource"
+
+
+def test_http_post_method_path(parsed_http_methods_routes):
+ """Test that POST method path is correctly extracted."""
+ post_route = next(
+ (r for r in parsed_http_methods_routes if r.method == "POST"), None
+ )
+
+ assert post_route is not None
+ assert post_route.path == "/resource"
+
+
+def test_http_put_method_presence(parsed_http_methods_routes):
+ """Test that PUT method is correctly extracted."""
+ put_route = next((r for r in parsed_http_methods_routes if r.method == "PUT"), None)
+
+ assert put_route is not None
+ assert put_route.operation_id == "updateResource"
+
+
+def test_http_put_method_path(parsed_http_methods_routes):
+ """Test that PUT method path is correctly extracted."""
+ put_route = next((r for r in parsed_http_methods_routes if r.method == "PUT"), None)
+
+ assert put_route is not None
+ assert put_route.path == "/resource"
+
+
+def test_http_delete_method_presence(parsed_http_methods_routes):
+ """Test that DELETE method is correctly extracted."""
+ delete_route = next(
+ (r for r in parsed_http_methods_routes if r.method == "DELETE"), None
+ )
+
+ assert delete_route is not None
+ assert delete_route.operation_id == "deleteResource"
+
+
+def test_http_delete_method_path(parsed_http_methods_routes):
+ """Test that DELETE method path is correctly extracted."""
+ delete_route = next(
+ (r for r in parsed_http_methods_routes if r.method == "DELETE"), None
+ )
+
+ assert delete_route is not None
+ assert delete_route.path == "/resource"
+
+
+def test_http_patch_method_presence(parsed_http_methods_routes):
+ """Test that PATCH method is correctly extracted."""
+ patch_route = next(
+ (r for r in parsed_http_methods_routes if r.method == "PATCH"), None
+ )
+
+ assert patch_route is not None
+ assert patch_route.operation_id == "patchResource"
+
+
+def test_http_patch_method_path(parsed_http_methods_routes):
+ """Test that PATCH method path is correctly extracted."""
+ patch_route = next(
+ (r for r in parsed_http_methods_routes if r.method == "PATCH"), None
+ )
+
+ assert patch_route is not None
+ assert patch_route.path == "/resource"
+
+
+def test_http_head_method_presence(parsed_http_methods_routes):
+ """Test that HEAD method is correctly extracted."""
+ head_route = next(
+ (r for r in parsed_http_methods_routes if r.method == "HEAD"), None
+ )
+
+ assert head_route is not None
+ assert head_route.operation_id == "headResource"
+
+
+def test_http_head_method_path(parsed_http_methods_routes):
+ """Test that HEAD method path is correctly extracted."""
+ head_route = next(
+ (r for r in parsed_http_methods_routes if r.method == "HEAD"), None
+ )
+
+ assert head_route is not None
+ assert head_route.path == "/resource"
+
+
+def test_http_options_method_presence(parsed_http_methods_routes):
+ """Test that OPTIONS method is correctly extracted."""
+ options_route = next(
+ (r for r in parsed_http_methods_routes if r.method == "OPTIONS"), None
+ )
+
+ assert options_route is not None
+ assert options_route.operation_id == "optionsResource"
+
+
+def test_http_options_method_path(parsed_http_methods_routes):
+ """Test that OPTIONS method path is correctly extracted."""
+ options_route = next(
+ (r for r in parsed_http_methods_routes if r.method == "OPTIONS"), None
+ )
+
+ assert options_route is not None
+ assert options_route.path == "/resource"
+
+
+def test_http_trace_method_presence(parsed_http_methods_routes):
+ """Test that TRACE method is correctly extracted."""
+ trace_route = next(
+ (r for r in parsed_http_methods_routes if r.method == "TRACE"), None
+ )
+
+ assert trace_route is not None
+ assert trace_route.operation_id == "traceResource"
+
+
+def test_http_trace_method_path(parsed_http_methods_routes):
+ """Test that TRACE method path is correctly extracted."""
+ trace_route = next(
+ (r for r in parsed_http_methods_routes if r.method == "TRACE"), None
+ )
+
+ assert trace_route is not None
+ assert trace_route.path == "/resource"
diff --git a/tests/utilities/openapi/test_openapi_fastapi.py b/tests/utilities/openapi/test_openapi_fastapi.py
new file mode 100644
index 000000000..0faf3103d
--- /dev/null
+++ b/tests/utilities/openapi/test_openapi_fastapi.py
@@ -0,0 +1,437 @@
+"""Tests for FastAPI integration with the OpenAPI utilities."""
+
+from typing import Any, Dict
+
+import pytest
+from fastapi import FastAPI
+
+from fastmcp.utilities.openapi import parse_openapi_to_http_routes
+
+
+def fastapi_server() -> FastAPI:
+ """Fixture that returns a FastAPI app for live OpenAPI schema testing."""
+ from enum import Enum
+ from typing import List, Optional
+
+ from fastapi import Body, Depends, Header, HTTPException, Path, Query
+ from pydantic import BaseModel, Field
+
+ class ItemStatus(str, Enum):
+ available = "available"
+ pending = "pending"
+ sold = "sold"
+
+ class Tag(BaseModel):
+ id: int
+ name: str
+
+ class Item(BaseModel):
+ """Example pydantic model for testing OpenAPI schema generation."""
+
+ name: str
+ description: Optional[str] = None
+ price: float
+ tax: Optional[float] = None
+ tags: List[str] = Field(default_factory=list)
+ status: ItemStatus = ItemStatus.available
+ dimensions: Optional[Dict[str, float]] = None
+
+ # Create a FastAPI app with comprehensive features
+ app = FastAPI(
+ title="Comprehensive Test API",
+ description="A test API with various OpenAPI features",
+ version="1.0.0",
+ )
+
+ def get_token_header(
+ x_token: str = Header(..., description="Authentication token"),
+ ):
+ """Example dependency function for header validation."""
+ if x_token != "fake-super-secret-token":
+ raise HTTPException(status_code=400, detail="X-Token header invalid")
+ return x_token
+
+ TokenDep = Depends(get_token_header)
+
+ @app.get(
+ "/items/",
+ operation_id="list_items",
+ summary="List all items",
+ description="Get a list of all items with optional filtering",
+ tags=["items"],
+ )
+ async def list_items(
+ skip: int = Query(0, description="Number of items to skip"),
+ limit: int = Query(10, description="Max number of items to return"),
+ status: Optional[ItemStatus] = Query(
+ None, description="Filter items by status"
+ ),
+ ):
+ """List all items with pagination and optional status filtering."""
+ fake_items = [
+ {"name": f"Item {i}", "price": float(i)} for i in range(skip, skip + limit)
+ ]
+ if status:
+ fake_items = [item for item in fake_items if item.get("status") == status]
+ return fake_items
+
+ @app.post(
+ "/items/",
+ operation_id="create_item",
+ summary="Create a new item",
+ tags=["items"],
+ status_code=201,
+ )
+ async def create_item(
+ item: Item = Body(..., description="Item to create"),
+ x_token: str = TokenDep,
+ ):
+ """Create a new item (requires authentication)."""
+ return item
+
+ @app.get(
+ "/items/{item_id}",
+ operation_id="get_item",
+ summary="Get a specific item by ID",
+ tags=["items"],
+ )
+ async def get_item(
+ item_id: int = Path(..., description="The ID of the item to retrieve"),
+ include_tax: bool = Query(
+ False, description="Whether to include tax information"
+ ),
+ ):
+ """Get details about a specific item."""
+ item = {
+ "id": item_id,
+ "name": f"Item {item_id}",
+ "price": float(item_id) * 10.0,
+ }
+ if include_tax:
+ item["tax"] = item["price"] * 0.2
+ return item
+
+ @app.put(
+ "/items/{item_id}",
+ operation_id="update_item",
+ summary="Update an existing item",
+ tags=["items"],
+ )
+ async def update_item(
+ item_id: int = Path(..., description="The ID of the item to update"),
+ item: Item = Body(..., description="Updated item data"),
+ x_token: str = TokenDep,
+ ):
+ """Update an existing item (requires authentication)."""
+ return {"item_id": item_id, **item.model_dump()}
+
+ @app.delete(
+ "/items/{item_id}",
+ operation_id="delete_item",
+ summary="Delete an item",
+ tags=["items"],
+ )
+ async def delete_item(
+ item_id: int = Path(..., description="The ID of the item to delete"),
+ x_token: str = TokenDep,
+ ):
+ """Delete an item (requires authentication)."""
+ return {"item_id": item_id, "deleted": True}
+
+ @app.patch(
+ "/items/{item_id}/tags",
+ operation_id="update_item_tags",
+ summary="Update item tags",
+ tags=["items", "tags"],
+ )
+ async def update_item_tags(
+ item_id: int = Path(..., description="The ID of the item"),
+ tags: List[str] = Body(..., description="Updated tags"),
+ ):
+ """Update just the tags of an item."""
+ return {"item_id": item_id, "tags": tags}
+
+ @app.get(
+ "/items/{item_id}/tags/{tag_id}",
+ operation_id="get_item_tag",
+ summary="Get a specific tag for an item",
+ tags=["items", "tags"],
+ )
+ async def get_item_tag(
+ item_id: int = Path(..., description="The ID of the item"),
+ tag_id: str = Path(..., description="The ID of the tag"),
+ ):
+ """Get a specific tag for an item."""
+ return {"item_id": item_id, "tag_id": tag_id}
+
+ @app.post(
+ "/upload/",
+ operation_id="upload_file",
+ summary="Upload a file",
+ tags=["files"],
+ )
+ async def upload_file(
+ file_name: str = Query(..., description="Name of the file"),
+ content_type: str = Query(..., description="Content type of the file"),
+ ):
+ """Upload a file (dummy endpoint for testing query params)."""
+ return {
+ "file_name": file_name,
+ "content_type": content_type,
+ "status": "uploaded",
+ }
+
+ # Add a callback route for testing complex documentation
+ @app.post(
+ "/webhook",
+ operation_id="register_webhook",
+ summary="Register a webhook",
+ tags=["webhooks"],
+ callbacks={ # type: ignore
+ "itemProcessed": {
+ "{$request.body.callbackUrl}": {
+ "post": {
+ "summary": "Callback for when an item is processed",
+ "requestBody": {
+ "required": True,
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "item_id": {"type": "integer"},
+ "status": {"type": "string"},
+ "timestamp": {
+ "type": "string",
+ "format": "date-time",
+ },
+ },
+ }
+ }
+ },
+ },
+ "responses": {
+ "200": {"description": "Webhook processed successfully"}
+ },
+ }
+ }
+ }
+ },
+ )
+ async def register_webhook(
+ callback_url: str = Body(
+ ..., embed=True, description="URL to call when processing completes"
+ ),
+ ):
+ """Register a webhook for processing notifications."""
+ return {"registered": True, "callback_url": callback_url}
+
+ return app
+
+
+def fastapi_openapi_schema(fastapi_server) -> Dict[str, Any]:
+ """Fixture that returns the OpenAPI schema from a live FastAPI server."""
+ return fastapi_server.openapi()
+
+
+def parsed_routes(fastapi_openapi_schema):
+ """Return parsed routes from a FastAPI OpenAPI schema."""
+ return parse_openapi_to_http_routes(fastapi_openapi_schema)
+
+
+def route_map(parsed_routes):
+ """Return a dictionary of routes by operation ID."""
+ return {r.operation_id: r for r in parsed_routes if r.operation_id is not None}
+
+
+def test_parse_fastapi_schema_route_count(parsed_routes):
+ """Test that all routes are parsed from the FastAPI schema."""
+ assert len(parsed_routes) == 9 # 8 endpoints + 1 callback
+
+
+def test_parse_fastapi_schema_operation_ids(route_map):
+ """Test that all expected operation IDs are present in the parsed schema."""
+ expected_operations = [
+ "list_items",
+ "create_item",
+ "get_item",
+ "update_item",
+ "delete_item",
+ "update_item_tags",
+ "get_item_tag",
+ "upload_file",
+ "register_webhook",
+ ]
+
+ for op_id in expected_operations:
+ assert op_id in route_map, f"Operation ID '{op_id}' not found in parsed routes"
+
+
+def test_path_parameter_parsing(route_map):
+ """Test that path parameters are correctly parsed."""
+ get_item = route_map["get_item"]
+ path_params = [p for p in get_item.parameters if p.location == "path"]
+
+ assert len(path_params) == 1
+ assert path_params[0].name == "item_id"
+ assert path_params[0].required is True
+
+
+def test_query_parameter_parsing(route_map):
+ """Test that query parameters are correctly parsed."""
+ list_items = route_map["list_items"]
+ query_params = [p for p in list_items.parameters if p.location == "query"]
+
+ assert len(query_params) == 3 # skip, limit, status
+ param_names = [p.name for p in query_params]
+ assert "skip" in param_names
+ assert "limit" in param_names
+ assert "status" in param_names
+
+
+def test_header_parameter_parsing(route_map):
+ """Test that header parameters from dependencies are correctly parsed."""
+ create_item = route_map["create_item"]
+ header_params = [p for p in create_item.parameters if p.location == "header"]
+
+ assert len(header_params) == 1
+ assert header_params[0].name == "x-token"
+ assert header_params[0].required is True
+
+
+def test_request_body_content_type(route_map):
+ """Test that request body content types are correctly parsed."""
+ create_item = route_map["create_item"]
+
+ assert create_item.request_body is not None
+ assert "application/json" in create_item.request_body.content_schema
+
+
+def test_request_body_properties(route_map):
+ """Test that request body properties are correctly parsed."""
+ create_item = route_map["create_item"]
+ json_schema = create_item.request_body.content_schema["application/json"]
+ properties = json_schema.get("properties", {})
+
+ assert "name" in properties
+ assert "price" in properties
+ assert "description" in properties
+ assert "tags" in properties
+ assert "status" in properties
+
+
+def test_request_body_status_schema(route_map):
+ """Test that the status schema in request body is correctly handled."""
+ create_item = route_map["create_item"]
+ json_schema = create_item.request_body.content_schema["application/json"]
+ properties = json_schema.get("properties", {})
+ status_schema = properties.get("status", {})
+
+ # FastAPI may represent enums as references or directly include enum values
+ assert "$ref" in status_schema or "enum" in status_schema
+
+
+def test_route_with_items_tag(parsed_routes):
+ """Test that routes with 'items' tag are correctly parsed."""
+ item_routes = [r for r in parsed_routes if "items" in r.tags]
+
+ assert len(item_routes) >= 6 # At least 6 endpoints with "items" tag
+
+
+def test_routes_with_multiple_tags(parsed_routes):
+ """Test that routes with multiple tags are correctly parsed."""
+ multi_tag_routes = [r for r in parsed_routes if len(r.tags) > 1]
+
+ assert len(multi_tag_routes) >= 2 # At least 2 endpoints with multiple tags
+
+
+def test_specific_route_tags(route_map):
+ """Test that specific routes have the expected tags."""
+ assert "items" in route_map["list_items"].tags
+ assert "items" in route_map["update_item_tags"].tags
+ assert "tags" in route_map["update_item_tags"].tags
+ assert "webhooks" in route_map["register_webhook"].tags
+
+
+def test_operation_summary(route_map):
+ """Test that operation summary is correctly parsed."""
+ list_items = route_map["list_items"]
+
+ assert list_items.summary == "List all items"
+
+
+def test_operation_description(route_map):
+ """Test that operation description is correctly parsed."""
+ list_items = route_map["list_items"]
+
+ assert list_items.description is not None
+ assert "optional filtering" in list_items.description
+
+
+def test_path_with_route_parameters(route_map):
+ """Test that paths with route parameters are correctly parsed."""
+ get_item = route_map["get_item"]
+
+ assert get_item.path == "/items/{item_id}"
+
+
+def test_complex_nested_paths(route_map):
+ """Test that complex nested paths are correctly parsed."""
+ get_item_tag = route_map["get_item_tag"]
+
+ assert get_item_tag.path == "/items/{item_id}/tags/{tag_id}"
+
+
+def test_http_methods(route_map):
+ """Test that HTTP methods are correctly parsed."""
+ assert route_map["list_items"].method == "GET"
+ assert route_map["create_item"].method == "POST"
+ assert route_map["update_item"].method == "PUT"
+ assert route_map["delete_item"].method == "DELETE"
+ assert route_map["update_item_tags"].method == "PATCH"
+
+
+def test_item_schema_properties(route_map):
+ """Test that Item schema properties are correctly resolved."""
+ create_item = route_map["create_item"]
+ json_schema = create_item.request_body.content_schema["application/json"]
+ properties = json_schema.get("properties", {})
+
+ assert "name" in properties
+ assert properties["name"]["type"] == "string"
+ assert "price" in properties
+ assert properties["price"]["type"] == "number"
+
+
+def test_webhook_endpoint(route_map):
+ """Test parsing of webhook registration endpoint."""
+ webhook = route_map["register_webhook"]
+
+ assert webhook.method == "POST"
+ assert webhook.path == "/webhook"
+
+
+def test_webhook_request_body(route_map):
+ """Test that webhook request body is correctly parsed."""
+ webhook = route_map["register_webhook"]
+
+ assert webhook.request_body is not None
+ assert "application/json" in webhook.request_body.content_schema
+ json_schema = webhook.request_body.content_schema["application/json"]
+ assert "callback_url" in json_schema.get("properties", {})
+
+
+def test_token_dependency_handling(route_map):
+ """Test that token dependencies are correctly handled in parsed endpoints."""
+ token_endpoints = ["create_item", "update_item", "delete_item"]
+
+ for op_id in token_endpoints:
+ route = route_map[op_id]
+ header_params = [p for p in route.parameters if p.location == "header"]
+ token_headers = [p for p in header_params if p.name == "x-token"]
+ assert len(token_headers) == 1, f"Expected x-token header in {op_id}"
+ assert token_headers[0].required is True