Django-rest-framework: Provide an easy way to document query params for detail_routes

[blueyed]

There does not seem to be an easy way to document query parameters for a detail
view.

1. Would it be feasible to support something like a input_serializer_class
   argument, from where CoreAPI Link Fields (with query for the "Query
   Parameters" used in docs/link.html) could be derived from?

2. This could then even set validated_data on the request (or pass a new
   argument for/with it)?

This would simplify the pattern with:

class CustomInputSerializer(serializers.Serializer):
    query_arg = serializers.CharField(required=True)


@detail_route(methods=['get'])
def custom_action(self, request, uuid=None):
    """Some custom action.

    Query arguments:

     - ``query_arg``:
       something, e.g. "2017-08-15" (**required**).
    """
    obj = self.get_object()

    input = CustomInputSerializer(data=request.GET)
    input.is_valid(raise_exception=True)

    # Use input.validated_data['query_arg']

to

…

@detail_route(methods=['get'])
def custom_action(self, request, uuid=None):
    """Some custom action."""
    obj = self.get_object()

    # Use request.validated_data['query_arg']

[carltongibson]

From v3.7 you'll be able to subclass AutoSchema on your view to customise the Link generation.

You can either override get_link directly (calling super I guess) or any of the get_X_fields methods, as you see fit:

https://github.com/encode/django-rest-framework/blob/5c2290d97380ca15005f7d42ffceae04dc817dba/rest_framework/schemas/inspectors.py#L165-L169

Given that you're using @detail_route you'll need to inspect self.view.action to determine when to add the extra fields.

I'm not sure about your other points. I'm inclined to think that whatever machinery would be needed to drop the two lines — and go straight to request.validated_data — would not be worth it. I quite like that you explicitly create the serialiser and call is_valid()...

[JoshAddington]

Is generating query parameter documentation in the documentation anywhere? I feel like the 'Documenting your API' page is pretty sparse on details or examples. If an example of what it takes for query parameter documentation to be generated was provided, that would be fantastic.