@@ -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+
385410def _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 ():
0 commit comments