Serializer Examples

[N1ark]

Describe the bug
Decorating a serializer with @extend_schema_serializer and example(s) removes pagination from the example.

To Reproduce

from rest_framework.serializers import ModelSerializer
from rest_framework.viewsets import ModelViewSet
from rest_framework.pagination import LimitOffsetPagination
from drf_spectacular.utils import extend_schema_serializer, OpenApiExample

@extend_schema_serializer(
    examples=[
        OpenApiExample('Example', value={'user': 123})
    ]
)
class BaseSerializer(ModelSerializer):
    class Meta:
        model = MyModel
        fields = ['user']

class MyViewSet(ModelViewSet):
	# setup variables, etc.
    pagination_class = LimitOffsetPagination

	@extend_schema(responses={
        200: BaseSerializer(many=True)
    })
    @action(detail=False, url_path='example')
    def my_view(self, request):
        pass

Expected behavior
I would expect the generated documentation to show the example provided for the serializer ({'user': 123}) in the paginated display:

{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "user": 123
    }
  ]
}

Instead, the example of the serializer seems to also override the paginated display:

{
  "user": 123
}

The paginated response only appears when no example is provided, and the example overrides the paginated response, rather than only the content of "results".

[N1ark]

Might be a duplicate of #595 !

[N1ark]

If this can help, I implemented a quick and dirty solution to this: https://github.com/N1ark/drf-spectacular.
Of course it isn't maintainable, and it made a bunch of tests fail, but it might help find a solution!

From what I understood (I am really new to this codebase), what happens (or rather, what doesn't) is that there is no actual example generation for endpoints when none is specified. So by default, the Swagger/Redoc view will generate an example from the information it has on the content of the response's schema. However adding an example will add it directly to the OA3 .yml file, regardless of pagination or if it's a list view.

Right now my solution was just to obtain the paginated schema (passing an empty {} value, to know where the example data needs to go), and then just creating a new OpenApiExample with the paginated data instead, but there might be a better way of doing this I'm unaware of.

If you're interested I'd be happy to clean up the solution a bit, and make a PR :)

[tfranzel]

Hey @N1ark,

thanks for having a try at this. Please open a PR to make this easier to talk about, even if we end up not using it. I'll try to look into it very soon.

[N1ark]

Done, #641 !

Thanks for the quick reply :)

[tfranzel]

@N1ark so thanks again for coming up with the concept. I basically reused it but accounted for several edge cases you were probably not aware of.

• {} is a valid schema so not 100% safe. use a sentinel instead.
• if a pagination schema is not as expected we would crash. wrapped this introspection in a try except and emit a warning.
• requests can also be lists
• did a copy instead of a new OpenApiExample as you would have to carry over 4 more fields otherwise.
• refrained from changing the names as some people are not using English.

glad this issue is finally resolved 🚀

[tfranzel]

closing this issue for now. feel free to comment if anything is missing or not working and we will follow-up.