Path parameters support in swagger

[saurabhgharatpara]

Is there a way to add path parameters in Gateway route or request method for Swagger. Right now if you create a manual json or yaml file for swagger, It shows up but it does not detect path parameters if it is defined in path.
For e.g if path is "/pet/{petId}" . petId cannot be entered

[tarsil]

Hi, I'm not sure of I understood you question properly but basically if I did, then what you need to do is simply, for example:

@get("/pet/{petid}")
async def get_pet(petid: str) -> JSONResponse:
# add your logic here to return

And then in the Gateway, you simply do:

Gateway(handler=get_pet)

All of this is in the docs thoroughly explained as well 🙂.

Esmerald automatically detects the path params. When you create a path param in the URL, you must pass it in the handler with the corresponding type.

[saurabhgharatpara]

the screenshot that ive attached is from swagger demo
https://petstore.swagger.io/#/pet/getPetById

When i implement in esmerald. It is showing as No Parameters

[tarsil]

Can you share your code where you define the Gateway and the handler, please?

[saurabhgharatpara]

Ok I've found the solution. So basically i needed to include the path parameter as an argument to function. It's working now. Thanks

[tarsil]

@saurabhgharatpara Yes, I mentioned that before

from esmerald import Esmerald, get, JSONResponse

# For handler

@get("/pet/{petid}")
async def get_pet(petid: str) -> JSONResponse:
    # add your logic here to return

# And then in the Gateway, you simply do:
Gateway(handler=get_pet)

Every path parameter and the type must be declared in the function handler in order to make sure it will be recognised.

[saurabhgharatpara]

I also want to ask about adding query parameters in swagger ? We can access query params by using
pet_name= request.query_params.get('pet_name')
But it is not visible in swagger UI
It is visible only when i add "pet_name" as an argument to function and to path

@get(summary="Retrieve the list of dog",
status_code=status.HTTP_200_OK)
async def get_pets(request: Request,
headers: dict, logger: Any,
pet_name:str="",
) -> Response:

also
Gateway(handler=get_pets, path="/pet?pet_name={pet_name}"),

Is there any other way or this is correct ?

[tarsil]

@saurabhgharatpara so, you are correct, for the query_params to be visible in the swagger UI you will need to declare those in the function as parameters as well. You don't need to declare that URL in the Gateway() as you did, when you put them in the the function as parameters it should be enough.

One thing to consider is the fact that if the query paramarers are not mandatory, then you must specificy the parameters as optional using the typing.Optional or the typing.Union[the type, None] or pass a default

Does this make sense?

[saurabhgharatpara]

if i change the gateway as
Gateway(handler=get_pets, path="/pet")

and function as
@get(summary="Retrieve the list of dog",
status_code=status.HTTP_200_OK)
async def get_pets(request: Request,
headers: dict, logger: Any,
pet_name:str="",
) -> Response:

Its not visible in the swagger UI

[tarsil]

if i change the gateway as Gateway(handler=get_pets, path="/pet")

and function as @get(summary="Retrieve the list of dog", status_code=status.HTTP_200_OK) async def get_pets(request: Request, headers: dict, logger: Any, pet_name:str="", ) -> Response:

Its not visible in the swagger UI

Hmm maybe a regression happened before. I will have a look and get back to you. In the meantime use the way you mentioned before. Thank you for spotting this

[tarsil]

@saurabhgharatpara this was a small regression introduced by a big feature 3 versions ago but its being addressed here #371

Soon (today or tomorrow) this should be released and no issues like this should happen again 👍🏼

[tarsil]

@saurabhgharatpara version 3.3.4 of Esmerald was released and this query parameters should not be an issue anymore.

There is also the documentation for it if you want https://www.esmerald.dev/extras/query-params/

[tarsil]

The reason for that @saurabhgharatpara its because of the operation id, they are the same because you have the same function called get_all_badges which I understand it and its ok and it works. This might be a swagger level of bug that I can look at it soon but try to add a different operation_id and let me know.

If it works in postman means Esmerald is ok, time to look at swagger.

Btw, I assume the dependency injection was addressed and understood.

EDIT: It was a swagger bug in the operation ids, not your code. You are doing well 👍🏼

[tarsil]

@saurabhgharatpara We will be releasing soon something that will also address this on a Gateway level and fixes this OpenAPI operation id situation.

[tarsil]

@saurabhgharatpara This should be addressed now in the version 3.3.6 of Esmerald and now the OpenAPI docs should be able to automatically parse to the right operation_id.

[saurabhgharatpara]

Okay thanks for your support

[tarsil]

Not a problem. Now everything should be ok

[saurabhgharatpara]

ive added q: Dict[str, str] = None as an arument for query params . query params is optional
but im getting this error

this is my function
async def test(request: Request, headers: dict, q: Dict[str, str] = None,
**kwargs: Any) -> Response:

[saurabhgharatpara]

This issue is solved by making changes in signature.py file for parse_values_for_connection function

def parse_values_for_connection(cls, connection: Union[Request, WebSocket], **kwargs: Dict[str, Any]) -> Any:
"""
Parses keyword arguments for connection, applies encoders if defined,
and retrieves validated model fields.

    Args:
        connection (Union[Request, WebSocket]): The connection object.
        kwargs (Any): Keyword arguments to parse.

    Returns:
        Dict[str, Any]: Dictionary of validated model fields.

    Raises:
        BaseSystemException: If validation error occurs.
        EncoderException: If encoder error occurs.
    """
    try:
        if cls.encoders:
            kwargs = cls.parse_encoders(kwargs)
        if not kwargs.get("q"):
            kwargs["q"] = {}
        signature = cls(**kwargs)
        values = {}
        for key in cls.model_fields:
            values[key] = signature.field_value(key)
        return values
    except ValidationError as e:
        raise cls.build_base_system_exception(connection, e) from e
    except Exception as e:
        raise cls.build_encoder_exception(connection, e) from e

[saurabhgharatpara]

Thankyou ... waiting for release soon

[saurabhgharatpara]

Hello .. any updates on this ?

[tarsil]

Hello .. any updates on this ?

Hey. So the internal implementation for this already happened but needs some other adjustments and documentation. We expect in the next couple of weeks to do the release

[saurabhgharatpara]

Okay..thank you for the update

[tarsil]

@saurabhgharatpara we found a possible bug in the OpenAPI representation and we will be doing a release now for other purposes (multi body) while we investigate further this but don't worries as we intend to make this clearer in a new release as well later with the query params.

[tarsil]

@saurabhgharatpara apologies for the time it took but we needed to investigate the source cause for this and it wasn't a simple thing. Not a bug from Esmerald but from one of the dependencies. This is now working 100% ok with the new version released just now. 3.4.1

Have a look at the release notes but it should now work like a charm for optional query params.

[tarsil]

@saurabhgharatpara i received an email with a reply from you but I can't find it in the conversation. Did you delete it?

[tarsil]

Good, case closed then.

[saurabhgharatpara]

Hello, im facing this issue in 3.4.1
Im getting this issue in swagger input should be valid dictionary

[tarsil]

Hello, im facing this issue in 3.4.1 Im getting this issue in swagger input should be valid dictionary

Thank you for this. I'm currently using Esmerald 3.4.2 (the latest) and I literally replicated this and I am not having issues at all.

No issues at all

[saurabhgharatpara]

Yes ive upgraded to latest version . its working Thanks

[tarsil]

Yes ive upgraded to latest version . its working Thanks

I found it weird as I didn't have that problem also with the version 3.4.1. Anyway, I'm glad it's addressed