Customizing detail_route Title and Description

[stephenHartzell]

I think help the API be more self-documenting if @detail_route allowed for a customizable title and description in the browsable API. Currently, the detail_route just takes the name of the model for the title and uses the description provided in the viewset. Perhaps the name of the detail_route method could be the default title, and a comment block for that method could be its default description.

[tomchristie]

Marking as an enhancement, but currently undecided.

[mateosss]

Is there any update on documenting @detail/list_route methods? Maybe this could be accomplished by having nested viewsets.

[xordoquy]

This may but that's out of that topic and we consider nesting urls is an antipattern.

[mateosss]

Thanks a lot! I didn't know that nested resource were considered an antipattern. That solves the nested resource documentation problem, because it shouldn't be used.
For anyone else that may come to the same issue as this one, this should help making them think twice before using nested resources.
http://stackoverflow.com/questions/20951419/what-are-best-practices-for-rest-nested-resources

[blag]

I did manage to get this working, but it was kind of a hack:

class ThingViewSet(viewsets.ModelViewSet):
    """
    ViewSet documentation
    """
    # ...

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        if hasattr(self.__class__, '__class_doc__'):
            self.__class__.__doc__ = self.__class__.__class_doc__
        else:
            # Have to cache this in a non-standard variable because we modify
            # self.__class__.__doc__ in detail_routes and list_routes
            self.__class__.__class_doc__ = self.__class__.__doc__

    @detail_route(methods=['get'], permission_classes=[...])
    def thing_detail(self, request, pk=None):
        """
        thing_detail documentation
        """
        self.__class__.__doc__ = self.thing_detail.__func__.__doc__
        # ...

I don't like it - it's not very Pythonic - but it works.

[blag]

Also, I think this tiny thread on the mailing list is relevant, so notifying those users might be a nice thing to do once this is fixed.

[tomchristie]

Descriptions now supported in multi-line docstrings, as per final part of http://www.django-rest-framework.org/api-guide/schemas/#schemas-as-documentation

Perhaps we'll improve this in the future, but that'll do for now.

[blag]

Thanks @tomchristie! So, just to make sure I understand how to create documentation for a custom endpoint...for (a slightly fixed/tweaked version of) my above ThingViewSet example I should be able to do something like this:

class ThingViewSet(viewsets.ModelViewSet):
    """
    ViewSet documentation - class docstring, using single line style
    
    retrieve: Documentation for GET on things/<pk>/
    
    list: Documentation for GET on things/
    """
    # ...
    
    @detail_route(methods=['get', 'post'], permission_classes=[...])
    def do_action_on_thing(self, request, pk=None):
        """
        action detail route documentation - method docstring, using multi-line style
        
        get:
        do_action_on_thing GET documentation - things/<pk>/do_action_on_thing
        
        post:
        do_action_on_thing POST documentation -  things/<pk>/do_action_on_thing/
        """
        # ...

and when users navigate their browsers to things/ and things/<pk>/ they should get the appropriate documentation from the ThingViewSet class docstring.

But then when users navigate their browsers to things/<pk>/do_action_on_thing/ they should get the GET/POST documentation from the do_action_on_thing method docstring and NOT the GET/POST documentation from the ThingViewSet class docstring.

Is my understanding correct?

[jnns]

I don't see the docstrings being picked up by the self-describing api – only by the newly introduced api docs.