drf-spectacular extend_schema_serializer can't do empty value example

Question

I'm using the extend_schema_serializer decorator to document examples of json data that can be sent in a POST request. The problem is, one of the variations/examples requires no data, but the generated swagger doc insists on showing what looks like an auto-generated default with all possible params. This isn't ideal when I'm trying to demonstrate the most simple examples.

I have this for the serializer.

@extend_schema_serializer(
    examples=[
        OpenApiExample(
            'Simple example',
            value={},
            request_only=True,
            response_only=False,
        ),
        OpenApiExample(
            'Single param example',
            value={
                'mult': 3,
            },
            request_only=True,
            response_only=False,
        ),
    ],
)
class RollChartSerializer(serializers.Serializer):
    mult = serializers.IntegerField(required=False, write_only=True)
    input_vars = serializers.DictField(required=False, write_only=True)
    foo_name = serializers.CharField(source="foo", allow_null=True, read_only=True)
    foo_url = ChartAbsoluteUrlField(source="foo.id", allow_null=True, read_only=True)
    results = serializers.StringRelatedField(many=True, read_only=True)
...

Where I have value={}, I've also tried value=None and have tried removing it altogether. In all cases, the 'example value' in swagger showing.

{
  "mult": 0,
  "input_vars": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

Is there something I'm missing?

I did notice that the generated redoc docs show null.

For the second example, swagger correctly shows

{
    "mult": 3
}

Answer 1

I'm not quite sure if they are related, but I had a similar output when I was using the @extend_schema_serializer with a nested serializer like this:

@extend_schema_serializer(
examples=[
    OpenApiExample(
        'Simple example',
        value=some data,
        request_only=True,
        response_only=False,
    ),
    OpenApiExample(
        'Single param example',
        value={another data,},
        request_only=True,
        response_only=False,
        ),
    ],
)
class UserSerializer(serializers.Serializer):
    email = serializers.EmailField()
    username = serializers.CharField(max_length=100)

class CommentSerializer(serializers.Serializer):
    user = UserSerializer()
    content = serializers.CharField(max_length=200)
    created = serializers.DateTimeField()

The correct way is like this:

class UserSerializer(serializers.Serializer):
    email = serializers.EmailField()
    username = serializers.CharField(max_length=100)

@extend_schema_serializer(
examples=[
    OpenApiExample(
        'Simple example',
        value=some data,
        request_only=True,
        response_only=False,
    ),
    OpenApiExample(
        'Single param example',
        value={another data,},
        request_only=True,
        response_only=False,
        ),
    ],
)
class CommentSerializer(serializers.Serializer):
    user = UserSerializer()
    content = serializers.CharField(max_length=200)
    created = serializers.DateTimeField()

I'm not sure if this will help, but you can include "required=False" in all your "RollChartSerializer" fields. Also, include a summary after the example names.