Query serializer support

[MissiaL]

In my current project i i find use query_serializer. Like this

class PublicCommentsRequest(Serializer):
    include = CharField(required=False)
    order_by = CharField(required=False)
    order_direction = ChoiceField(choices=['ASC', 'DESC'], required=False)
    start_datetime = DateTimeField(required=False)
    end_datetime = DateTimeField(required=False)
    unsafe = BooleanField(required=False)

swagger_auto_schema(
    query_serializer=PublicCommentsRequest,
    deprecated=True,
    tags=['comments'],
    operation_id='public:get_comments',
),

It looks like this

Could you add similar functionality?

I could use extra_parameters, but it looks complicated
Thanks

[tfranzel]

that looks interesting. i need to refactor the parameter section. the old code did some funky stuff that needs changing. i'll try to incorporate this with it.

[MissiaL]

Any updates? Maybe I can help you somehow?

[tfranzel]

sry too keep you waiting. i had to do some heavy structural changes. this will be the next feature. 😄
apart from that feature how far along are you on your project? is spectacular covering most of it already?

[MissiaL]

It seems that this is the last feature that remains to be implemented. Otherwise, it looks like it’s ready :-)

[tfranzel]

So OpenAPI3 has multiple ways achieving this. could you post an example query for that?

option 1: exploding the serializer into seperate fields, as if OpenApiParameter was used multiple times
option 2: An object with those fields as parameters. like a nested serializer packed into one query parameter

and option 2 has even more sub-options for formatting and serialization. i think this is one of the more complicated sections of the spec.

[MissiaL]

If I understand you correctly, then you need to give an example of how this should look?
It seems to me that the parameter should be able to accept two types of objects:
Serializer and OpenApiParameter

One example

class PublicCommentsRequest(Serializer):
    include = CharField(required=False)
    order_by = CharField(required=False)
    order_direction = ChoiceField(choices=['ASC', 'DESC'], required=False)
    start_datetime = DateTimeField(required=False)
    end_datetime = DateTimeField(required=False)

@extend_schema(
    parameters=[PublicCommentsRequest,OpenApiParameter('expiration_date', OpenApiTypes.DATETIME, description='time the object will expire at')],
    responses={201: None},
 )

[tfranzel]

unfortunately, there is more info required to build the schema here. i suppose you refer to option1. i was asking about how the actual query will look like, that is how this is supposed to look in the query section of the HTTP request.

https://swagger.io/docs/specification/serialization/#query

Object id = {"role": "admin", "firstName": "Alex"}

• form/explode=True:/users?role=admin&firstName=Alex (option 1)
• form/explode=False:/users?id=role,admin,firstName,Alex (option 2 variation 1)
• deepObject: /users?id[role]=admin&id[firstName]=Alex (option 2 variation 2)

option2 has even more variations.

[MissiaL]

Wow, I didn't think there were so many different options!
I think we could try to make the simplest basic option 1

Perhaps then it will be possible to expand it somehow. It’s better to make a simple option, and then gradually complicate it, if necessary

[tsouvarev]

I think that option 1 is the most used by far in REST APIs

[tfranzel]

@tsouvarev yes i think so too.
@MissiaL yes option 1 looks good. i already prepared something. i need to streamline it though. i prob will have something for you by tomorrow.

[tfranzel]

@MissiaL: i had a hard look and decided to do it as you suggested.

parameters=[...,serializer] for query exploding (as it is used most offen)

parameters=[...,OpenApiParamter(serializer)], intended for nesting (but style and explode are not exposed yet. ) swagger explodes it automatically in that case also because of the defaults. so atm they result in the "same" in swagger-ui (even though the generated spec is slightly different)

i think that should do it for now.

[MissiaL]

Thanks! It works great!
I have a couple more improvements that I will add now.

#12