Improve documentation regarding serializer class on extra actions.

[soerface]

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 https://github.com/encode/django-rest-framework/pull/5605#issuecomment-345420265

[xordoquy]

Hi,

Thank you for the contribution. The issue with this PR is that it's specific to serializer_class while it could also cover throttling, permissions and so on. I'd rather see something more opened such as "it takes as arguments the class properties such as serializer_class"

[soerface]

I see, actually, right after the example, it says exactly that. I just didn't get it. Still, I would like to contribute the fix of the example code, passing the serializer_class argument (and use self.get_serializer() if I'm not mistaken, see review). I think that the example caused the confusion with me and others trying to use a custom serializer class.

[soerface]

The kwarg is necessary, regardless of usage inside the function. Without the kwarg, the generated doc will show the UserSerializer form, not the PasswordSerializer form. That is the reason why I had trouble with understanding the decorator, I didn't knew how to change the form.

I feel that it might be common that extra actions have other inputs than the normal actions. Therefore I think it's a good idea to show correct usage of another serializer.

[carltongibson]

Hi @soerface. Yes, right. I'm thinking then we should rephrase a little bit to spell that out. (Note emphasis on little.)

Happy if you want have a pop at that. If not I'll give it a look over.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.