Bug: Examples should serialize under parameters when using Path parameters

[leandrodamascena]

Expected Behaviour

Original report: https://github.com/aws-powertools/powertools-lambda-python/pull/5575/files#r1846670069

The examples should be under parameters, not under schema.
https://swagger.io/specification/#parameter-object

I was not able to change the output location of the examples. In this PR, it will only enable the definition of examples in the Schema Object.
https://swagger.io/specification/#schema-object

wrong

        "parameters": [
          {
            "required": false,
            "schema": {
              "type": "integer",
              "exclusiveMaximum": 100.0,
              "exclusiveMinimum": 0.0,
              "title": "Count",
              "default": 1,
              "examples": [
                {
                  "summary": "Example 1",
                  "description": null,
                  "value": 10,
                  "externalValue": null
                }
              ]
            },
            "name": "count",
            "in": "query"
          }
        ],

expected

        "parameters": [
          {
            "required": false,
            "schema": {
              "type": "integer",
              "exclusiveMaximum": 100.0,
              "exclusiveMinimum": 0.0,
              "title": "Count",
              "default": 1
            },
            "examples": [
              {
                "summary": "Example 1",
                "description": null,
                "value": 10,
                "externalValue": null
              }
            ],
            "name": "count",
            "in": "query"
          }
        ],

Current Behaviour

This is being serialized under schema and not showing in SwaggerUI.

        "parameters": [
          {
            "required": false,
            "schema": {
              "type": "integer",
              "exclusiveMaximum": 100.0,
              "exclusiveMinimum": 0.0,
              "title": "Count",
              "default": 1,
              "examples": [
                {
                  "summary": "Example 1",
                  "description": null,
                  "value": 10,
                  "externalValue": null
                }
              ]
            },
            "name": "count",
            "in": "query"
          }
        ],

Code snippet

from typing import Annotated, List

import requests
from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.utilities.typing import LambdaContext
from aws_lambda_powertools.event_handler.openapi.params import Path
from aws_lambda_powertools.event_handler.openapi.models import Example
from pydantic import BaseModel, Field
from dataclasses import dataclass

app = APIGatewayRestResolver(enable_validation=True)
app.enable_swagger(path="/swagger")  # (1)!



@app.get("/todos/<todo_id>")
def get_todo_by_id(todo_id: Annotated[str, Path(examples=Example(summary='a',value="1"))]) -> str:
    todo = requests.get("https://jsonplaceholder.typicode.com/todos")
    todo.raise_for_status()

    return "test"


def lambda_handler(event: dict, context: LambdaContext) -> dict:
    return app.resolve(event, context)


if __name__ == "__main__":
    print(app.get_openapi_json_schema())

Possible Solution

No response

Steps to Reproduce

Run the code above

Powertools for AWS Lambda (Python) version

latest

AWS Lambda function runtime

3.13

Packaging format used

Lambda Layers, PyPi

Debugging logs

[tonsho]

In FastAPI, the example definitions for JSON Schema and OpenAPI are handled separately.
I think it would be better to follow this approach in Powertools as well and prepare openapi_examples separately.

openapi_examples: Optional[Dict[str, Example]] = None

https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter

https://github.com/fastapi/fastapi/blob/0.115.5/fastapi/params.py#L69