Use Serializer in extend_schema.parameters (use serializer as OpenApiParameter?)

[xuhuiding0612]

Hi This is actually a question, I did a lot of searches and can't find the suggested way to use serializer as OpenApiParameter:
Currently I am using this way:

extend_schema(
        operation_id="op1",
        description="",
        tags=["tag1"],
        parameters=[MyQueryParamSerializer],    <-
        request=MyRequestBodySerializer,
        responses={
            status.HTTP_200_OK: OpenApiResponse()
        }
)

This works for 0.16. But with the new version release three days ago (0.17).

It will start giving warnings starting tag 0.17.0 like:

error: List item 0 has incompatible type "Type[MyQueryParamSerializer]"; expected "OpenApiParameter"

So my question would be what's the preferred way to use Serializer(s) as OpenApiParameter(s)? Thanks for the answering and help!

[tfranzel]

Hi,

the only difference there is that we enabled mypy. this feature still works the same, we just forgot to account for that case in the type hints. apart from the mypy warning, this should still work as expected. i will fix the type.

the tests do cover several cases for parameters:

drf-spectacular/tests/test_extend_schema.py

Lines 151 to 155 in 812d3ff

	@extend_schema(parameters=[
	QuerySerializer, # exploded
	OpenApiParameter('nested', QuerySerializer) # nested
	])
	@action(detail=False, url_path='serializer-query', methods=['GET'])

[tfranzel]

| So my question would be what's the preferred way to use Serializer(s) as OpenApiParameter(s)? Thanks for the answering and help!

i didn't really answer the question. it depends on what you want. the option you chose explodes the serializer into separate parameters fields, however you do not have more configuration options there.

if you wrap the serializer in a OpenApiParameter, the serializer is nested under one "name", but you can still control how this is handled via the style and explode parameters (c.f. OpenAPI doc).

so it really depends on what you want. also note that request-wise this may look the same, while swagger-ui will present this in different ways.

[tfranzel]

that should fix the warning. i would have liked to turn mypy on on our tests too. as a matter of fact your issue was in there. unfortunately there are so many false positives due to the way the tests are structured. it was too cumbersome.

[xuhuiding0612]

I appreciate the quick and detailed response! Since I have python manage.py spectacular –validate enabled now. I will fix the version to 0.16.0 temporarily. Once the type hints is updated in future version I will upgrade~
Thanks!

[tfranzel]

i think there is a misconception here. spectacular --validate only validates the generated schema. it does not run code linting tools. something else is running mypy on your side.

[tfranzel]

i'll close this issue for now as this is only a typing warning that has no direct impact. the type hint is fixed and will be part of 0.17.1

[janneronkko]

We were also hit by this issue after updating our dependencies.

I blacklisted the 0.17.0 version in our setup.py so that we won't get that version.

Could you release 0.17.1 as soon as possible so people would not need to spend time on finding out why they get type errors after updating drf-spectacular?

[tfranzel]

hi @janneronkko sry for the inconvenience. i'll do it very soon. i need to look at 2 other issues first. probably tomorrow.