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

[leandrodamascena]

Adding this item to work in the next iteration starting next week.

[leandrodamascena]

I have a PR to fix this issue and will merge it next week.

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

This issue is now closed. Please be mindful that future comments are hard for our team to see.

If you need more assistance, please either tag a team member or open a new issue that references this one.

If you wish to keep having a conversation with other community members under this issue feel free to do so.

[github-actions]

This is now released under 3.7.0 version!