From 963607a1841fd98d17a2a3cfe690902f7204b915 Mon Sep 17 00:00:00 2001 From: Soeren Wegener Date: Fri, 18 Jan 2019 12:23:00 +0100 Subject: [PATCH] Improve documentation regarding serializer class on extra actions. The documentation does currently not describe how to use a custom `serializer_class` with extra actions. The example uses a custom serializer without using the seralizer_class attribute, resulting in the generated documentation page presenting the wrong form. The author of the feature described the usage of the `serializer_class` kwarg in his pr #5605: https://github.com/encode/django-rest-framework/pull/5605#issuecomment-345420265 --- docs/api-guide/viewsets.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md index e7cf4d48f..ada6367bf 100644 --- a/docs/api-guide/viewsets.md +++ b/docs/api-guide/viewsets.md @@ -129,6 +129,11 @@ You may inspect these attributes to adjust behaviour based on the current action If you have ad-hoc methods that should be routable, you can mark them as such with the `@action` decorator. Like regular actions, extra actions may be intended for either a single object, or an entire collection. To indicate this, set the `detail` argument to `True` or `False`. The router will configure its URL patterns accordingly. e.g., the `DefaultRouter` will configure detail actions to contain `pk` in their URL patterns. +Your custom action may use a different [Serializer class](serializers.md). To make sure that the generated docs display a form which matches your serializer, you have two options: + +* Either: provide a `serializer_class=MySerializer` argument to the `@action()` decorator (see example below) +* Or: override the `get_serializer_class()` method as described in [GenericAPIView](generic-views.md#genericapiview) + A more complete example of extra actions: from django.contrib.auth.models import User @@ -144,7 +149,7 @@ A more complete example of extra actions: queryset = User.objects.all() serializer_class = UserSerializer - @action(detail=True, methods=['post']) + @action(detail=True, methods=['post'], serializer_class=PasswordSerializer) def set_password(self, request, pk=None): user = self.get_object() serializer = PasswordSerializer(data=request.data)