Views with swappable serializers are failing for docs

[gabn88]

Checklist

• I have verified that that issue exists against the master branch of Django REST framework.
• I have searched for similar issues in both open and closed tickets and cannot find a duplicate.
• This is not a usage question. (Those should be directed to the discussion group instead.)
• This cannot be dealt with as a third party library. (We prefer new functionality to be in the form of third party libraries where possible.)
• I have reduced the issue to the simplest possible case.
• I have included a failing test as a pull request. (If you are unable to do so we can still accept the issue.)

Steps to reproduce

For me the only logical way to create an endpoint with nested data was to use a nested serializer on GET, but a flat serializer on POST/PATCH/PUT actions. This is easily achieved by doing (from http://stackoverflow.com/a/21325719/3849359 ):

class SwappableSerializerMixin(object):
    def get_serializer_class(self):
        try:
            return self.serializer_classes[self.request.method]
        except AttributeError as e:
            logger.debug('%(cls)s does not have the required serializer_classes'
                         'property' % {'cls': self.__class__.__name__})
            raise AttributeError
        except KeyError:
            logger.debug('request method %(method)s is not listed'
                         ' in %(cls)s serializer_classes' %
                         {'cls': self.__class__.__name__,
                          'method': self.request.method})
            # required if you don't include all the methods (option, etc) in your serializer_class
            return super(SwappableSerializerMixin, self).get_serializer_class()

However, for the docs this obviously fails, as self.request is None.

Expected behavior

Determine the serializer based on other params for the docs.

Actual behavior

AttributeError is raised, because self.request is None.

[carltongibson]

This has come up on Django Filter a number of times, as users are expecting the request to be present, which in schema generation contexts isn't guaranteed to be the case.

Currently users need to make sure that they can handle the request is None case.

I'm still digging in here. The notes on Using an Explicit Schema View show passing the request, and SchemaView does exactly that so it looks like we should be able to get the request in place. (??)

[gabn88]

I don't really understand how the SchemaView works, does it take the request from the actual request? (a.k. GET /schema/) or does it mocks all the different request types (GET/POST/PUT/PATCH/DELETE) to generate the different endpoints for the scheme? If it is the first, giving the request will not generate a real representation of the actual API, will it?

[carltongibson]

@gabn88 This is somewhat complex.

SchemaGenerator clones the actual request — that you make requesting /schema/, say — and adjusts the method

But: get_docs_view sets public=True which means the request parameter to get_links will be None when using that.

[m1kola]

As far as I understand, the problem is that SchemaGenerator generates static schema and it's not aware of dynamic parameters. So use cases shown in your example and in this example from the official documentation are not currently supported:

def get_serializer_class(self):
    if self.request.user.is_staff:
        return FullAccountSerializer
    return BasicAccountSerializer

Another case: parameters that are available only together with other parameters. For example /api/pages endpoint serves different types of pages and allows you to filter them by type. If you specify type=my_page_type you can also specify a list of extra fields that you want to receive for this specific page (eg. fields=title,intro,author). So the fields parameter is not available if the type is not specified.

[tomchristie]

@m1kola - not currently supported

Not quite true - we do per-user schemas, but see @carltongibson's comment above.
Issue still needs proper review tho.

[carltongibson]

This is related to #4980. Once we highlight how to configure the docs view for yourself, the public parameter will make more sense.

Beyond that we need highlight that get_serializer must be prepared to handle request=None.

After #5443, we will at least:

• get docs rendered, rather than an error
• get a warning logged as to what happened to the serialiser fields.