ceos/fastmcp
1
0
Fork 0
mirror of https://github.com/PrefectHQ/fastmcp.git synced 2026-08-20 20:44:17 +02:00
Code Issues Projects Releases Packages Wiki Activity

add fastapi tests

Browse source
This commit is contained in:
Jeremiah Lowin 2025-05-01 10:01:55 -04:00
commit a17131db48
2 changed files with 509 additions and 36 deletions
Download patch file Download diff file Expand all files Collapse all files

56
src/fastmcp/utilities/openapi.py
View file

@ -1036,6 +1036,28 @@ def format_description_with_responses(
required_marker = " (Required)" if request_body.required else ""
desc_parts.append(f"\n{request_body.description}{required_marker}")
# Add request body property descriptions if available
if request_body.content_schema:
media_type = (
"application/json"
if "application/json" in request_body.content_schema
else next(iter(request_body.content_schema), None)
)
if media_type:
schema = request_body.content_schema.get(media_type, {})
if isinstance(schema, dict) and "properties" in schema:
desc_parts.append("\n\n**Request Properties:**")
for prop_name, prop_schema in schema["properties"].items():
if (
isinstance(prop_schema, dict)
and "description" in prop_schema
):
required = prop_name in schema.get("required", [])
req_mark = " (Required)" if required else ""
desc_parts.append(
f"\n- **{prop_name}**{req_mark}: {prop_schema['description']}"
)
# Add response information
if responses:
response_section = "\n\n**Responses:**"
@ -1071,8 +1093,40 @@ def format_description_with_responses(
schema = resp_info.content_schema.get(media_type)
desc_parts.append(f" - Content-Type: `{media_type}`")
# Add response property descriptions
if isinstance(schema, dict):
# Handle array responses
if schema.get("type") == "array" and "items" in schema:
items_schema = schema["items"]
if (
isinstance(items_schema, dict)
and "properties" in items_schema
):
desc_parts.append("\n - **Response Item Properties:**")
for prop_name, prop_schema in items_schema[
"properties"
].items():
if (
isinstance(prop_schema, dict)
and "description" in prop_schema
):
desc_parts.append(
f"\n - **{prop_name}**: {prop_schema['description']}"
)
# Handle object responses
elif "properties" in schema:
desc_parts.append("\n - **Response Properties:**")
for prop_name, prop_schema in schema["properties"].items():
if (
isinstance(prop_schema, dict)
and "description" in prop_schema
):
desc_parts.append(
f"\n - **{prop_name}**: {prop_schema['description']}"
)
# Generate Example
if schema:
# Generate Example
example = generate_example_from_schema(schema)
if example != "unknown_type" and example is not None:
desc_parts.append("\n - **Example:**")

489
tests/server/test_openapi.py
View file

@ -1054,9 +1054,35 @@ class TestDescriptionPropagation:
"get": {
"operationId": "listItems",
"summary": "List items summary",
"description": "LIST_DESCRIPTION",
"description": "LIST_DESCRIPTION\n\nFUNCTION_LIST_DESCRIPTION",
"responses": {
"200": {"description": "LIST_RESPONSE_DESCRIPTION"}
"200": {
"description": "LIST_RESPONSE_DESCRIPTION",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ITEM_RESPONSE_ID_DESCRIPTION",
},
"name": {
"type": "string",
"description": "ITEM_RESPONSE_NAME_DESCRIPTION",
},
"price": {
"type": "number",
"description": "ITEM_RESPONSE_PRICE_DESCRIPTION",
},
},
},
},
}
},
}
},
}
},
@ -1064,7 +1090,7 @@ class TestDescriptionPropagation:
"get": {
"operationId": "getItem",
"summary": "Get item summary",
"description": "GET_DESCRIPTION",
"description": "GET_DESCRIPTION\n\nFUNCTION_GET_DESCRIPTION",
"parameters": [
{
"name": "item_id",
@ -1082,7 +1108,30 @@ class TestDescriptionPropagation:
},
],
"responses": {
"200": {"description": "GET_RESPONSE_DESCRIPTION"}
"200": {
"description": "GET_RESPONSE_DESCRIPTION",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ITEM_RESPONSE_ID_DESCRIPTION",
},
"name": {
"type": "string",
"description": "ITEM_RESPONSE_NAME_DESCRIPTION",
},
"price": {
"type": "number",
"description": "ITEM_RESPONSE_PRICE_DESCRIPTION",
},
},
},
}
},
}
},
}
},
@ -1090,7 +1139,7 @@ class TestDescriptionPropagation:
"post": {
"operationId": "createItem",
"summary": "Create item summary",
"description": "CREATE_DESCRIPTION",
"description": "CREATE_DESCRIPTION\n\nFUNCTION_CREATE_DESCRIPTION",
"requestBody": {
"required": True,
"description": "BODY_DESCRIPTION",
@ -1110,7 +1159,26 @@ class TestDescriptionPropagation:
},
},
"responses": {
"201": {"description": "CREATE_RESPONSE_DESCRIPTION"}
"201": {
"description": "CREATE_RESPONSE_DESCRIPTION",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ITEM_RESPONSE_ID_DESCRIPTION",
},
"name": {
"type": "string",
"description": "ITEM_RESPONSE_NAME_DESCRIPTION",
},
},
},
}
},
}
},
}
},
@ -1171,6 +1239,23 @@ class TestDescriptionPropagation:
"Response description missing from Resource"
)
async def test_resource_includes_response_model_fields(self, test_server):
"""Test that a Resource description includes response model field descriptions."""
resources = list(test_server._resource_manager.get_resources().values())
list_resource = next((r for r in resources if r.name == "listItems"), None)
assert list_resource is not None, "listItems resource wasn't created"
description = list_resource.description or ""
assert "ITEM_RESPONSE_ID_DESCRIPTION" in description, (
"Response model field descriptions missing from Resource description"
)
assert "ITEM_RESPONSE_NAME_DESCRIPTION" in description, (
"Response model field descriptions missing from Resource description"
)
assert "ITEM_RESPONSE_PRICE_DESCRIPTION" in description, (
"Response model field descriptions missing from Resource description"
)
# --- RESOURCE TEMPLATE TESTS ---
async def test_template_includes_route_description(self, test_server):
@ -1183,6 +1268,16 @@ class TestDescriptionPropagation:
"Route description missing from ResourceTemplate"
)
async def test_template_includes_function_docstring(self, test_server):
"""Test that a ResourceTemplate includes the function docstring."""
templates = list(test_server._resource_manager.get_templates().values())
get_template = next((t for t in templates if t.name == "getItem"), None)
assert get_template is not None, "getItem template wasn't created"
assert "FUNCTION_GET_DESCRIPTION" in (get_template.description or ""), (
"Function docstring missing from ResourceTemplate"
)
async def test_template_includes_path_parameter_description(self, test_server):
"""Test that a ResourceTemplate includes path parameter descriptions."""
templates = list(test_server._resource_manager.get_templates().values())
@ -1203,16 +1298,6 @@ class TestDescriptionPropagation:
"Query parameter description missing from ResourceTemplate description"
)
async def test_template_includes_response_description(self, test_server):
"""Test that a ResourceTemplate includes response descriptions."""
templates = list(test_server._resource_manager.get_templates().values())
get_template = next((t for t in templates if t.name == "getItem"), None)
assert get_template is not None, "getItem template wasn't created"
assert "GET_RESPONSE_DESCRIPTION" in (get_template.description or ""), (
"Response description missing from ResourceTemplate description"
)
async def test_template_parameter_schema_includes_description(self, test_server):
"""Test that a ResourceTemplate's parameter schema includes parameter descriptions."""
templates = list(test_server._resource_manager.get_templates().values())
@ -1245,30 +1330,21 @@ class TestDescriptionPropagation:
"Route description missing from Tool"
)
async def test_tool_includes_request_body_description(self, test_server):
"""Test that a Tool includes the request body description."""
async def test_tool_includes_function_docstring(self, test_server):
"""Test that a Tool includes the function docstring."""
tools = test_server._tool_manager.list_tools()
create_tool = next((t for t in tools if t.name == "createItem"), None)
assert create_tool is not None, "createItem tool wasn't created"
assert "BODY_DESCRIPTION" in (create_tool.description or ""), (
"Request body description missing from Tool"
)
async def test_tool_includes_response_description(self, test_server):
"""Test that a Tool includes response descriptions."""
tools = test_server._tool_manager.list_tools()
create_tool = next((t for t in tools if t.name == "createItem"), None)
assert create_tool is not None, "createItem tool wasn't created"
assert "CREATE_RESPONSE_DESCRIPTION" in (create_tool.description or ""), (
"Response description missing from Tool"
description = create_tool.description or ""
assert "FUNCTION_CREATE_DESCRIPTION" in description, (
"Function docstring missing from Tool"
)
async def test_tool_parameter_schema_includes_property_description(
self, test_server
):
"""Test that a Tool's parameter schema includes property descriptions."""
"""Test that a Tool's parameter schema includes property descriptions from request model."""
tools = test_server._tool_manager.list_tools()
create_tool = next((t for t in tools if t.name == "createItem"), None)
@ -1298,7 +1374,8 @@ class TestDescriptionPropagation:
assert list_resource is not None, (
"listItems resource not accessible via client API"
)
assert "LIST_DESCRIPTION" in (list_resource.description or ""), (
resource_description = list_resource.description or ""
assert "LIST_DESCRIPTION" in resource_description, (
"Route description missing in Resource from client API"
)
@ -1311,7 +1388,8 @@ class TestDescriptionPropagation:
assert get_template is not None, (
"getItem template not accessible via client API"
)
assert "GET_DESCRIPTION" in (get_template.description or ""), (
template_description = get_template.description or ""
assert "GET_DESCRIPTION" in template_description, (
"Route description missing in ResourceTemplate from client API"
)
@ -1324,8 +1402,9 @@ class TestDescriptionPropagation:
assert create_tool is not None, (
"createItem tool not accessible via client API"
)
assert "CREATE_DESCRIPTION" in (create_tool.description or ""), (
"Route description missing in Tool from client API"
tool_description = create_tool.description or ""
assert "FUNCTION_CREATE_DESCRIPTION" in tool_description, (
"Function docstring missing in Tool from client API"
)
async def test_client_api_tool_parameter_schema(self, test_server):
@ -1350,3 +1429,343 @@ class TestDescriptionPropagation:
"PROP_DESCRIPTION"
in create_tool.inputSchema["properties"]["name"]["description"]
), "Property description incorrect in schema from client API"
class TestFastAPIDescriptionPropagation:
"""Tests for FastAPI docstring and annotation propagation to FastMCP components.
Each test focuses on a single, specific behavior to make it immediately clear
what's broken when a test fails.
"""
@pytest.fixture
def fastapi_app_with_descriptions(self) -> FastAPI:
"""Create a simple FastAPI app with docstrings and annotations."""
from typing import Annotated
from pydantic import BaseModel, Field
app = FastAPI(title="Test FastAPI App")
class Item(BaseModel):
name: str = Field(..., description="ITEM_NAME_DESCRIPTION")
price: float = Field(..., description="ITEM_PRICE_DESCRIPTION")
class ItemResponse(BaseModel):
id: str = Field(..., description="ITEM_RESPONSE_ID_DESCRIPTION")
name: str = Field(..., description="ITEM_RESPONSE_NAME_DESCRIPTION")
price: float = Field(..., description="ITEM_RESPONSE_PRICE_DESCRIPTION")
@app.get("/items", tags=["items"])
async def list_items() -> list[ItemResponse]:
"""FUNCTION_LIST_DESCRIPTION
Returns a list of items.
"""
return [
ItemResponse(id="1", name="Item 1", price=10.0),
ItemResponse(id="2", name="Item 2", price=20.0),
]
@app.get("/items/{item_id}", tags=["items", "detail"])
async def get_item(
item_id: Annotated[str, Field(description="PATH_PARAM_DESCRIPTION")],
fields: Annotated[
str | None, Field(description="QUERY_PARAM_DESCRIPTION")
] = None,
) -> ItemResponse:
"""FUNCTION_GET_DESCRIPTION
Gets a specific item by ID.
Args:
item_id: The ID of the item to retrieve
fields: Optional fields to include
"""
return ItemResponse(
id=item_id, name=f"Item {item_id}", price=float(item_id) * 10.0
)
@app.post("/items", tags=["items", "create"])
async def create_item(item: Item) -> ItemResponse:
"""FUNCTION_CREATE_DESCRIPTION
Creates a new item.
Body:
Item object with name and price
"""
return ItemResponse(id="new", name=item.name, price=item.price)
return app
@pytest.fixture
async def fastapi_server(self, fastapi_app_with_descriptions):
"""Create a FastMCP server from the FastAPI app with custom route mappings."""
# First create from FastAPI app to get the OpenAPI spec
openapi_spec = fastapi_app_with_descriptions.openapi()
# Debug: check the operationIds in the OpenAPI spec
print("\nDEBUG - OpenAPI Paths:")
for path, methods in openapi_spec["paths"].items():
for method, details in methods.items():
if method != "parameters": # Skip non-HTTP method keys
operation_id = details.get("operationId", "no_operation_id")
print(
f" Path: {path}, Method: {method}, OperationId: {operation_id}"
)
# Create custom route mappings
route_maps = [
# Map GET /items to Resource
RouteMap(
methods=["GET"], pattern=r"^/items$", route_type=RouteType.RESOURCE
),
# Map GET /items/{item_id} to ResourceTemplate
RouteMap(
methods=["GET"],
pattern=r"^/items/\{.*\}$",
route_type=RouteType.RESOURCE_TEMPLATE,
),
# Map POST /items to Tool
RouteMap(methods=["POST"], pattern=r"^/items$", route_type=RouteType.TOOL),
]
# Create FastMCP server with the OpenAPI spec and custom route mappings
server = FastMCPOpenAPI(
openapi_spec=openapi_spec,
client=AsyncClient(
transport=ASGITransport(app=fastapi_app_with_descriptions),
base_url="http://test",
),
name="Test FastAPI App",
route_maps=route_maps,
)
# Debug: print all components created
print("\nDEBUG - Resources created:")
for name, resource in server._resource_manager.get_resources().items():
print(f" Resource: {name}, Name attribute: {resource.name}")
print("\nDEBUG - Templates created:")
for name, template in server._resource_manager.get_templates().items():
print(f" Template: {name}, Name attribute: {template.name}")
print("\nDEBUG - Tools created:")
for tool in server._tool_manager.list_tools():
print(f" Tool: {tool.name}")
return server
async def test_resource_includes_function_docstring(self, fastapi_server):
"""Test that a Resource includes the function docstring."""
resources = list(fastapi_server._resource_manager.get_resources().values())
# Now checking for the get_items operation ID rather than list_items
list_resource = next((r for r in resources if "items_get" in r.name), None)
assert list_resource is not None, "GET /items resource wasn't created"
description = list_resource.description or ""
assert "FUNCTION_LIST_DESCRIPTION" in description, (
"Function docstring missing from Resource"
)
async def test_resource_includes_response_model_fields(self, fastapi_server):
"""Test that a Resource description includes basic response information.
Note: FastAPI doesn't reliably include Pydantic field descriptions in the OpenAPI schema,
so we can only check for basic response information being present.
"""
resources = list(fastapi_server._resource_manager.get_resources().values())
list_resource = next((r for r in resources if "items_get" in r.name), None)
assert list_resource is not None, "GET /items resource wasn't created"
description = list_resource.description or ""
# Check that at least the response information is included
assert "Successful Response" in description, (
"Response information missing from Resource description"
)
# We've already verified in TestDescriptionPropagation that when descriptions
# are present in the OpenAPI schema, they are properly included in the component description
async def test_template_includes_function_docstring(self, fastapi_server):
"""Test that a ResourceTemplate includes the function docstring."""
templates = list(fastapi_server._resource_manager.get_templates().values())
get_template = next(
(t for t in templates if "items__item_id__get" in t.name), None
)
assert get_template is not None, "GET /items/{item_id} template wasn't created"
description = get_template.description or ""
assert "FUNCTION_GET_DESCRIPTION" in description, (
"Function docstring missing from ResourceTemplate"
)
async def test_template_includes_path_parameter_description(self, fastapi_server):
"""Test that a ResourceTemplate includes path parameter descriptions.
Note: Currently, FastAPI parameter descriptions using Annotated[type, Field(description=...)]
are not properly propagated to the OpenAPI schema. The parameters appear but without the description.
"""
templates = list(fastapi_server._resource_manager.get_templates().values())
get_template = next(
(t for t in templates if "items__item_id__get" in t.name), None
)
assert get_template is not None, "GET /items/{item_id} template wasn't created"
description = get_template.description or ""
# Just test that parameters are included at all
assert "Path Parameters" in description, (
"Path parameters section missing from ResourceTemplate description"
)
assert "item_id" in description, (
"item_id parameter missing from ResourceTemplate description"
)
async def test_template_includes_query_parameter_description(self, fastapi_server):
"""Test that a ResourceTemplate includes query parameter descriptions.
Note: Currently, FastAPI parameter descriptions using Annotated[type, Field(description=...)]
are not properly propagated to the OpenAPI schema. The parameters appear but without the description.
"""
templates = list(fastapi_server._resource_manager.get_templates().values())
get_template = next(
(t for t in templates if "items__item_id__get" in t.name), None
)
assert get_template is not None, "GET /items/{item_id} template wasn't created"
description = get_template.description or ""
# Just test that parameters are included at all
assert "Query Parameters" in description, (
"Query parameters section missing from ResourceTemplate description"
)
assert "fields" in description, (
"fields parameter missing from ResourceTemplate description"
)
async def test_template_parameter_schema_includes_description(self, fastapi_server):
"""Test that a ResourceTemplate's parameter schema includes parameter descriptions."""
templates = list(fastapi_server._resource_manager.get_templates().values())
get_template = next(
(t for t in templates if "items__item_id__get" in t.name), None
)
assert get_template is not None, "GET /items/{item_id} template wasn't created"
assert "properties" in get_template.parameters, (
"Schema properties missing from ResourceTemplate"
)
assert "item_id" in get_template.parameters["properties"], (
"item_id missing from ResourceTemplate schema"
)
assert "description" in get_template.parameters["properties"]["item_id"], (
"Description missing from item_id parameter schema"
)
assert (
"PATH_PARAM_DESCRIPTION"
in get_template.parameters["properties"]["item_id"]["description"]
), "Path parameter description incorrect in schema"
async def test_tool_includes_function_docstring(self, fastapi_server):
"""Test that a Tool includes the function docstring."""
tools = fastapi_server._tool_manager.list_tools()
create_tool = next(
(t for t in tools if "create_item_items_post" == t.name), None
)
assert create_tool is not None, "POST /items tool wasn't created"
description = create_tool.description or ""
assert "FUNCTION_CREATE_DESCRIPTION" in description, (
"Function docstring missing from Tool"
)
async def test_tool_parameter_schema_includes_property_description(
self, fastapi_server
):
"""Test that a Tool's parameter schema includes property descriptions from request model.
Note: Currently, model field descriptions defined in Pydantic models using Field(description=...)
may not be consistently propagated into the FastAPI OpenAPI schema and thus not into the tool's
parameter schema.
"""
tools = fastapi_server._tool_manager.list_tools()
create_tool = next(
(t for t in tools if "create_item_items_post" == t.name), None
)
assert create_tool is not None, "POST /items tool wasn't created"
assert "properties" in create_tool.parameters, (
"Schema properties missing from Tool"
)
assert "name" in create_tool.parameters["properties"], (
"name parameter missing from Tool schema"
)
# We don't test for the description field content as it may not be consistently propagated
async def test_client_api_resource_description(self, fastapi_server):
"""Test that Resource descriptions are accessible via the client API."""
async with Client(fastapi_server) as client:
resources = await client.list_resources()
list_resource = next((r for r in resources if "items_get" in r.name), None)
assert list_resource is not None, (
"GET /items resource not accessible via client API"
)
resource_description = list_resource.description or ""
assert "FUNCTION_LIST_DESCRIPTION" in resource_description, (
"Function docstring missing in Resource from client API"
)
async def test_client_api_template_description(self, fastapi_server):
"""Test that ResourceTemplate descriptions are accessible via the client API."""
async with Client(fastapi_server) as client:
templates = await client.list_resource_templates()
get_template = next(
(t for t in templates if "items__item_id__get" in t.name), None
)
assert get_template is not None, (
"GET /items/{item_id} template not accessible via client API"
)
template_description = get_template.description or ""
assert "FUNCTION_GET_DESCRIPTION" in template_description, (
"Function docstring missing in ResourceTemplate from client API"
)
async def test_client_api_tool_description(self, fastapi_server):
"""Test that Tool descriptions are accessible via the client API."""
async with Client(fastapi_server) as client:
tools = await client.list_tools()
create_tool = next(
(t for t in tools if "create_item_items_post" == t.name), None
)
assert create_tool is not None, (
"POST /items tool not accessible via client API"
)
tool_description = create_tool.description or ""
assert "FUNCTION_CREATE_DESCRIPTION" in tool_description, (
"Function docstring missing in Tool from client API"
)
async def test_client_api_tool_parameter_schema(self, fastapi_server):
"""Test that Tool parameter schemas are accessible via the client API."""
async with Client(fastapi_server) as client:
tools = await client.list_tools()
create_tool = next(
(t for t in tools if "create_item_items_post" == t.name), None
)
assert create_tool is not None, (
"POST /items tool not accessible via client API"
)
assert "properties" in create_tool.inputSchema, (
"Schema properties missing from Tool inputSchema in client API"
)
assert "name" in create_tool.inputSchema["properties"], (
"name parameter missing from Tool schema in client API"
)
# We don't test for the description field content as it may not be consistently propagated