Skip to content

Commit ac301a7

Browse files
fix(event_handler): correct six OpenAPI schema inaccuracies (#8630)
* fix(event_handler): correct six OpenAPI schema inaccuracies Signed-off-by: Abhishek Jha <abhi91temp@gmail.com> * fix(event_handler): correct six OpenAPI schema inaccuracies Signed-off-by: Abhishek Jha <abhi91temp@gmail.com> * fix(event_handler): correct six OpenAPI schema inaccuracies Signed-off-by: Abhishek Jha <abhi91temp@gmail.com> * fix(event_handler): correct six OpenAPI schema inaccuracies Signed-off-by: Abhishek Jha <abhi91temp@gmail.com> * refactor(event_handler): reuse _validate_openapi_extension_keys in get_openapi_schema to keep ruff complexity limits * test(event_handler): add regression tests for the six OpenAPI schema fixes * fix(event_handler): warn instead of raising when an OpenAPI extension key lacks the x- prefix --------- Signed-off-by: Abhishek Jha <abhi91temp@gmail.com> Co-authored-by: Leandro Damascena <lcdama@amazon.pt>
1 parent 7ce6851 commit ac301a7

10 files changed

Lines changed: 231 additions & 20 deletions

File tree

‎aws_lambda_powertools/event_handler/api_gateway.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1867,6 +1867,7 @@ def get_openapi_schema(
18671867
get_definitions,
18681868
)
18691869
from aws_lambda_powertools.event_handler.openapi.models import OpenAPI, PathItem, Tag
1870+
from aws_lambda_powertools.event_handler.openapi.schema_generator import _validate_openapi_extension_keys
18701871
from aws_lambda_powertools.event_handler.openapi.types import (
18711872
COMPONENT_REF_TEMPLATE,
18721873
)
@@ -1889,6 +1890,8 @@ def get_openapi_schema(
18891890
if not isinstance(openapi_extensions, dict):
18901891
openapi_extensions = {}
18911892

1893+
_validate_openapi_extension_keys(openapi_extensions)
1894+
18921895
output: dict[str, Any] = {
18931896
"openapi": openapi_version,
18941897
"info": info,

‎aws_lambda_powertools/event_handler/middlewares/openapi_validation.py‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@
2727
RequestValidationError,
2828
ResponseValidationError,
2929
)
30-
from aws_lambda_powertools.event_handler.openapi.params import Param, UploadFile
30+
from aws_lambda_powertools.event_handler.openapi.params import Param, ParamTypes, UploadFile
3131
from aws_lambda_powertools.event_handler.openapi.types import UnionType
3232
from aws_lambda_powertools.utilities.data_classes.alb_event import ALBEvent
3333
from aws_lambda_powertools.utilities.data_classes.vpc_lattice import VPCLatticeEventV2
@@ -430,6 +430,11 @@ def _request_params_to_args(
430430
loc = (field_info.in_.value, field.alias)
431431
value = received_params.get(field.alias)
432432

433+
# Route args are keyed by the path-template placeholder (the Python argument
434+
# name), so an explicit Path alias must not make the param unsatisfiable.
435+
if value is None and field_info.in_ == ParamTypes.path and field.name in received_params:
436+
value = received_params[field.name]
437+
433438
# If we don't have a value, see if it's required or has a default
434439
if value is None:
435440
_handle_missing_field_value(field, values, errors, loc)

‎aws_lambda_powertools/event_handler/openapi/encoders.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -327,6 +327,11 @@ def decimal_encoder(dec_value: Decimal) -> int | float:
327327
>>> decimal_encoder(Decimal("1"))
328328
1
329329
"""
330+
if not dec_value.is_finite():
331+
raise SerializationError(
332+
f"Unable to serialize the Decimal value {dec_value} as it is not finite.",
333+
"See: https://docs.powertools.aws.dev/lambda/python/latest/core/event_handler/api_gateway/#serializing-objects",
334+
)
330335
if dec_value.as_tuple().exponent >= 0: # type: ignore[operator]
331336
return int(dec_value)
332337
else:

‎aws_lambda_powertools/event_handler/openapi/schema_generator.py‎

Lines changed: 46 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -253,6 +253,8 @@ def _build_responses(
253253
dependant=dependant,
254254
model_name_map=model_name_map,
255255
field_mapping=field_mapping,
256+
resp_code=resp_code,
257+
status_code=status_code,
256258
)
257259
else:
258260
response_schema = _build_return_schema(
@@ -353,8 +355,13 @@ def _create_regular_parameter(
353355
field_mapping=field_mapping,
354356
)
355357

358+
# Path parameter names must match the route-template placeholders, which are
359+
# keyed by the Python argument name - an explicit alias would otherwise emit
360+
# a name that does not exist in the path template.
361+
param_name = param.name if field_info.in_.value == "path" else param.alias
362+
356363
parameter: dict[str, Any] = {
357-
"name": param.alias,
364+
"name": param_name,
358365
"in": field_info.in_.value,
359366
"required": param.required,
360367
"schema": param_schema,
@@ -370,18 +377,36 @@ def _create_regular_parameter(
370377
return parameter
371378

372379

373-
def _get_basic_type_schema(param_type: type) -> dict[str, str]:
380+
def _get_basic_type_schema(param_type: type) -> dict[str, Any]:
374381
"""Get basic OpenAPI schema for simple types."""
375-
type_map: dict[type, str] = {bool: "boolean", int: "integer", float: "number"}
376382
try:
377-
for base_type, schema_type in type_map.items():
378-
if issubclass(param_type, base_type):
379-
return {"type": schema_type}
380-
return {"type": "string"}
381-
except TypeError:
383+
from pydantic import TypeAdapter
384+
385+
return TypeAdapter(param_type).json_schema()
386+
except Exception:
382387
return {"type": "string"}
383388

384389

390+
def _validate_openapi_extension_keys(openapi_extensions: dict[str, Any]) -> None:
391+
"""Warn when an OpenAPI extension key does not respect the x- prefix convention.
392+
393+
The OpenAPI spec reserves the `x-` prefix for extensions. We warn instead of raising so that
394+
applications already serving a schema with a wrong key keep working; this becomes an error in v4.
395+
"""
396+
import warnings
397+
398+
from aws_lambda_powertools.warnings import PowertoolsUserWarning
399+
400+
for extension_key in openapi_extensions:
401+
if not str(extension_key).startswith("x-"):
402+
warnings.warn(
403+
f"OpenAPI extension key `{extension_key}` must start with `x-`; it is still emitted, "
404+
"but this will become an error in a future major version.",
405+
category=PowertoolsUserWarning,
406+
stacklevel=2,
407+
)
408+
409+
385410
def _apply_optional_fields(
386411
operation: dict[str, Any],
387412
*,
@@ -392,6 +417,7 @@ def _apply_optional_fields(
392417
if security:
393418
operation["security"] = security
394419
if openapi_extensions:
420+
_validate_openapi_extension_keys(openapi_extensions)
395421
operation.update(openapi_extensions)
396422

397423

@@ -501,16 +527,21 @@ def _build_custom_response(
501527
dependant: Dependant,
502528
model_name_map: dict[TypeModelOrEnum, str],
503529
field_mapping: dict[tuple[ModelField, Literal["validation", "serialization"]], JsonSchemaValue],
530+
resp_code: int,
531+
status_code: int = DEFAULT_STATUS_CODE,
504532
) -> OpenAPIResponse:
505533
"""Build a single custom response, resolving model references in content."""
506534
if "content" not in response:
507-
response["content"] = {
508-
DEFAULT_CONTENT_TYPE: _build_return_schema(
509-
param=dependant.return_param,
510-
model_name_map=model_name_map,
511-
field_mapping=field_mapping,
512-
),
513-
}
535+
# Only the route's own status code inherits the return-type schema;
536+
# description-only entries (e.g. a 404) stay description-only.
537+
if resp_code == status_code:
538+
response["content"] = {
539+
DEFAULT_CONTENT_TYPE: _build_return_schema(
540+
param=dependant.return_param,
541+
model_name_map=model_name_map,
542+
field_mapping=field_mapping,
543+
),
544+
}
514545
return response
515546

516547
for content_type, payload in response["content"].items():

‎aws_lambda_powertools/event_handler/openapi/types.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@
3535
# For security reasons, we hide **msg** details (don't leak Python, Pydantic or filenames)
3636
"type": {"title": "Error Type", "type": "string"},
3737
},
38-
"required": ["loc", "msg", "type"],
38+
"required": ["loc", "type"],
3939
}
4040

4141
validation_error_response_definition = {

‎tests/functional/event_handler/_pydantic/test_openapi_encoders.py‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -242,3 +242,14 @@ def serializer(value):
242242

243243
# THEN we should get the custom serializer output
244244
assert result == {"kind": "serialized"}
245+
246+
247+
@pytest.mark.parametrize("value", ["NaN", "Infinity", "-Infinity"])
248+
def test_openapi_encode_non_finite_decimal_raises_serialization_error(value):
249+
from decimal import Decimal
250+
251+
# GIVEN a Decimal that has no JSON number representation
252+
# WHEN we try to encode it
253+
# THEN we raise a SerializationError instead of leaking a TypeError
254+
with pytest.raises(SerializationError, match="not finite"):
255+
jsonable_encoder(Decimal(value))

‎tests/functional/event_handler/_pydantic/test_openapi_extensions.py‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
import json
44

5+
import pytest
6+
57
from aws_lambda_powertools.event_handler.api_gateway import APIGatewayRestResolver, Router
68
from aws_lambda_powertools.event_handler.openapi.models import (
79
APIKey,
@@ -11,6 +13,7 @@
1113
OAuthFlows,
1214
Server,
1315
)
16+
from aws_lambda_powertools.warnings import PowertoolsUserWarning
1417

1518

1619
def test_openapi_extension_root_level():
@@ -266,3 +269,31 @@ def lambda_handler_post():
266269
assert (
267270
schema["paths"]["/test"]["post"]["x-amazon-apigateway-request-validator"] == openapi_extension_validator_detail
268271
)
272+
273+
274+
def test_openapi_extension_root_level_warns_without_x_prefix():
275+
# GIVEN an APIGatewayRestResolver instance
276+
app = APIGatewayRestResolver()
277+
278+
# WHEN we get the OpenAPI schema with a root extension that does not start with x-
279+
# THEN we warn and still emit the schema, so existing applications keep working
280+
with pytest.warns(PowertoolsUserWarning, match="must start with `x-`"):
281+
schema = json.loads(app.get_openapi_json_schema(openapi_extensions={"amazon-apigateway-cors": {"maxAge": 0}}))
282+
283+
assert schema["amazon-apigateway-cors"] == {"maxAge": 0}
284+
285+
286+
def test_openapi_extension_operation_level_warns_without_x_prefix():
287+
# GIVEN a route with an operation extension that does not start with x-
288+
app = APIGatewayRestResolver()
289+
290+
@app.get("/test", openapi_extensions={"amazon-apigateway-integration": {"type": "aws_proxy"}})
291+
def lambda_handler():
292+
pass
293+
294+
# WHEN we get the OpenAPI schema
295+
# THEN we warn and the extension is still emitted on the operation
296+
with pytest.warns(PowertoolsUserWarning, match="must start with `x-`"):
297+
schema = json.loads(app.get_openapi_json_schema())
298+
299+
assert schema["paths"]["/test"]["get"]["amazon-apigateway-integration"] == {"type": "aws_proxy"}

‎tests/functional/event_handler/_pydantic/test_openapi_params.py‎

Lines changed: 78 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
import json
22
from dataclasses import dataclass
33
from datetime import datetime
4+
from enum import Enum
45
from typing import Annotated, Literal
56

67
import pytest
7-
from pydantic import BaseModel, Field
8+
from pydantic import BaseModel, ConfigDict, Field
89

910
from aws_lambda_powertools.event_handler.api_gateway import APIGatewayRestResolver, Response, Router
1011
from aws_lambda_powertools.event_handler.openapi.models import (
@@ -71,7 +72,10 @@ def search_handler(params: Annotated[QueryParams, Query()]):
7172
elif param.name == "search":
7273
assert param.required is False # Optional field
7374
assert param.description == "Search term"
74-
assert param.schema_.type == "string"
75+
# str | None is rendered as an anyOf, not a bare string
76+
assert param.schema_.type is None
77+
assert param.schema_.anyOf is not None
78+
assert [s.type for s in param.schema_.anyOf] == ["string", "null"]
7579

7680

7781
def test_openapi_pydantic_header_params():
@@ -119,7 +123,10 @@ def protected_handler(headers: Annotated[HeaderParams, Header()]):
119123
elif param.name == "accept-language":
120124
assert param.required is False # Optional field
121125
assert param.description == "Language preference"
122-
assert param.schema_.type == "string"
126+
# str | None is rendered as an anyOf, not a bare string
127+
assert param.schema_.type is None
128+
assert param.schema_.anyOf is not None
129+
assert [s.type for s in param.schema_.anyOf] == ["string", "null"]
123130

124131

125132
def test_openapi_pydantic_mixed_params():
@@ -1668,3 +1675,71 @@ def handler(x_custom: Annotated[str, Header]) -> dict:
16681675
assert result["statusCode"] == 200
16691676
response_body = json.loads(result["body"])
16701677
assert response_body["header"] == "my-value"
1678+
1679+
1680+
def test_openapi_query_model_fields_keep_their_types():
1681+
# GIVEN a Pydantic model used as Query() with optional, sequence and Enum fields
1682+
class Color(Enum):
1683+
red = "red"
1684+
blue = "blue"
1685+
1686+
class Filters(BaseModel):
1687+
limit: int | None = None
1688+
tags: list[str] = []
1689+
color: Color = Color.red
1690+
1691+
app = APIGatewayRestResolver(enable_validation=True)
1692+
1693+
@app.get("/search")
1694+
def search(filters: Annotated[Filters, Query()]):
1695+
return filters.model_dump()
1696+
1697+
# WHEN we get the OpenAPI schema
1698+
schema = json.loads(app.get_openapi_json_schema())
1699+
parameters = {p["name"]: p["schema"] for p in schema["paths"]["/search"]["get"]["parameters"]}
1700+
1701+
# THEN each field keeps its own type instead of collapsing to string
1702+
assert parameters["limit"] == {"anyOf": [{"type": "integer"}, {"type": "null"}]}
1703+
assert parameters["tags"] == {"type": "array", "items": {"type": "string"}}
1704+
assert parameters["color"]["enum"] == ["red", "blue"]
1705+
assert parameters["color"]["type"] == "string"
1706+
1707+
1708+
def test_openapi_query_model_arbitrary_type_falls_back_to_string():
1709+
# GIVEN a Pydantic model used as Query() with a field whose type has no JSON schema
1710+
class Opaque:
1711+
pass
1712+
1713+
class Filters(BaseModel):
1714+
model_config = ConfigDict(arbitrary_types_allowed=True)
1715+
token: Opaque
1716+
1717+
app = APIGatewayRestResolver(enable_validation=True)
1718+
1719+
@app.get("/search")
1720+
def search(filters: Annotated[Filters, Query()]):
1721+
return {}
1722+
1723+
# WHEN we get the OpenAPI schema
1724+
schema = json.loads(app.get_openapi_json_schema())
1725+
parameters = {p["name"]: p["schema"] for p in schema["paths"]["/search"]["get"]["parameters"]}
1726+
1727+
# THEN the field is documented as a string rather than failing schema generation
1728+
assert parameters["token"] == {"type": "string"}
1729+
1730+
1731+
def test_openapi_validation_error_schema_does_not_require_hidden_msg():
1732+
# GIVEN a resolver with validation enabled
1733+
app = APIGatewayRestResolver(enable_validation=True)
1734+
1735+
@app.get("/")
1736+
def handler():
1737+
return {}
1738+
1739+
# WHEN we get the OpenAPI schema
1740+
schema = json.loads(app.get_openapi_json_schema())
1741+
1742+
# THEN the ValidationError component only requires the fields it actually exposes
1743+
validation_error = schema["components"]["schemas"]["ValidationError"]
1744+
assert validation_error["required"] == ["loc", "type"]
1745+
assert "msg" not in validation_error["properties"]

‎tests/functional/event_handler/_pydantic/test_openapi_responses.py‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import json
12
from secrets import randbelow
23

34
from pydantic import BaseModel
@@ -492,3 +493,32 @@ def items_by_name() -> dict[str, Item]:
492493
dict_schema = schema.paths["/items/by-name"].get.responses[200].content["application/json"].schema_
493494
assert dict_schema.type == "object"
494495
assert dict_schema.additionalProperties.ref == "#/components/schemas/Item"
496+
497+
498+
def test_openapi_custom_response_without_content_keeps_description_only():
499+
# GIVEN a route with a return type and a description-only custom response for another status code
500+
class Todo(BaseModel):
501+
id: int
502+
503+
app = APIGatewayRestResolver(enable_validation=True)
504+
505+
@app.get(
506+
"/todos/<todo_id>",
507+
responses={
508+
200: {"description": "The todo"},
509+
404: {"description": "Todo not found"},
510+
201: {"description": "Created"},
511+
},
512+
)
513+
def get_todo(todo_id: int) -> Todo:
514+
return Todo(id=todo_id)
515+
516+
# WHEN we get the OpenAPI schema
517+
schema = json.loads(app.get_openapi_json_schema())
518+
responses = schema["paths"]["/todos/{todo_id}"]["get"]["responses"]
519+
520+
# THEN only the route's own status code carries the return-type content
521+
assert responses["200"]["description"] == "The todo"
522+
assert "content" in responses["200"]
523+
assert responses["404"] == {"description": "Todo not found"}
524+
assert responses["201"] == {"description": "Created"}

0 commit comments

Comments
 (0)