Is it possible to provide examples for query parameters when defining them in a serializer?

[bluelight773]

I know I can do the following:

    @extend_schema(
        parameters=[
            OpenApiParameter(
                "query_param1",
                type={"type": "array", "items": {"type": "integer"}}, style="form", explode=False,
            ),
            OpenApiParameter(
                "query_param2",
                examples=[
                    OpenApiExample("QP2 example", value="qp2 example value"),
                ],
            ),
            OpenApiParameter(
                "query_param3",
                examples=[
                    OpenApiExample("QP3 example", value="qp3 example value"),
                ],
            ),
       ])

I would like to do the same thing but using serializers. I tried the following, but no examples show up in SwaggerUI and then even if it were to work, it doesn't seem like I'd have a way to specify an example name for each parameter ("QP2 example" and "QP3 example").

@extend_schema_serializer(
    examples=[
        OpenApiExample(
            "QP2 and QP3 example",
            value={
                "query_param2": "qp2 example",
                "query_param3": "qp3_example"
            },
            request_only=True,
            response_only=False,
        ),
    ],
)
class QueryParamsSerializer(serializers.Serializer):
    query_param1 = serializers.ListSerializer(child=serializers.IntegerField())
    query_param2 = serializers.CharField()
    query_param3 = serializers.CharField()




@extend_schema(
    parameters=[QueryParamsSerializer])

Is there a way to achieve what I'm looking for (ie, provide examples for individual query parameters) using serializers or must I not rely on serializers when it comes to query parameters and use the standard OpenApiParameter way?

A separate issue I also noticed is that when using serializers for query_param1 , it works as if explode=True. Is there a way to make it work like in the regular OpenApiParameter definition with style="form", explode=False?

[tfranzel]

but no examples show up in SwaggerUI and then even if it were to work, ...

examples injected via extend_schema_serializer for parameters is simply not implemented I believe. nobody ever asked for it :smile:

... it doesn't seem like I'd have a way to specify an example name for each parameter ("QP2 example" and "QP3 example").

yep.. examples are all or nothing for serializers.

Is there a way to achieve what I'm looking for (ie, provide examples for individual query parameters) using serializers or must I not rely on serializers when it comes to query parameters and use the standard OpenApiParameter way?

putting in serializers directly is a convenience shorthand for exploding the fields into individual parameters. If that does not fit your case you must default to the regular usage, since there is no good way of adding extra info the the serializer there.

This feels like you are trying to put the rectangular piece in the round hole. Treat the serializer parameter explosion as a convenience method for the most common use-case. For everything else you need to use the regular approach.