How to document ModelViewSet methods?

[tonioo]

Hi,
is there a way to document ModelViewSet default methods (list, retrieve, etc.) without overloading them? I've tried to put some documentation in the class level docstring but it's not working:

"""
viewset.

retrieve: Return the given instance.

list: Return a list of all existing instances.

create: Create a new instance.
"""

[tfranzel]

Hi @tonioo, we don't do interpretation of the docstring. what we do support is having a docstring on the view class that gets propagated to each endpoint in that view. @extend_schema may then override what was found in the class docstring.

class level docstring but it's not working

by that you mean it is not split up? the whole docstring should show up in description though.

i'm but hesitant about introducing docstring processing.

[tonioo]

@tfranzel yes, I mean it is not split up but it's the expected behavior according to what you say.

I can indeed use the @extend_schema decorator but it means I need to overload every default method just for the documentation... Maybe a class decorator would be a better answer?

[tfranzel]

yes, that is the expected behaviour currently.

@extend_schema on the view is a good idea in theory. actually it already works on views with limited functionality. however, i made a design mistake there, which is hard to recover from. the problem is that the class decorator is applied after the method decorator. thus mixing both could lead to hard to understand override mechanics, but i have not given up on this yet.

in comparison docstring parsing would probably be the solution with the least amount of surprises. its not an ideal situation.

[tfranzel]

i figured out a way to resolve the above mentioned "override mechanics" problem. after we fix that, the path is open to add this functionality via view decoration.

[tonioo]

@tfranzel Good news. What's your idea?

[tfranzel]

something in the direction of

@extend_schem_view(
    retrieve=extend_schema(request=Foo, response=Foo)
    custom_action=extend_schema(request=Foo, response=Foo)
)
class YourModelViewset(viewsets.ModelViewSet)
    queryset = M.objects.none()

[tonioo]

@tfranzel Makes sense.

[v1k45]

@tonioo You can also use method_decorator to achieve this:

@method_decorator(extend_schema(operation_id='patchPost'), name='partial_update')
@method_decorator(extend_schema(operation_id='deletePost'), name='destroy')
class PostViewSet(viewsets.ModelViewSet):
    serializer_class = PostSerializer
    queryset = Post.objects.all()

@tfranzel This however, doesn't seem to work with custom actions. Custom actions have to be decorated explicitly while defining.

[tfranzel]

~~@v1k45 a good idea in principle but i recommend not doing that. @extend_schema is an invasive (non-pure) decorator. by using @method_decorator, you are most likely patching def partial_update(): in the UpdateModelMixin and thus having your extend_schema changes reflected in all views using the UpdateModelMixin.

currently working on extend_schema_view which takes that issue into account. it's close to done.

Edit: it turns out it's not as bad as i thought. DRF and the method_decorator are doing something smarter, but i have not completetly understood how. a quick test did not produce the problem is was expecting. anyway, i would be cautious.

[tfranzel]

@v1k45 as it turns out, method_decorator is doing something quite smart and is safe to use, but as you noticed this smart behavior does not always work for us.

@tonioo i added the new extend_schema_view decorator as outlined. please thoroughly check if everything works out fine. it was a tricky change.

[v1k45]

extend_schema_view is certainly a better and cleaner solution for this. Thanks!

[hmpf]

Works for me as well.