Django-rest-framework: allow serializers to override schema

[dhaval-mehta]

Checklist

• [x] I have verified that that issue exists against the master branch of the Django REST framework.
• [ ] I have searched for similar issues in both open and closed tickets and cannot find a duplicate.
• [x] This is not a usage question. (Those should be directed to the discussion group instead.)
• [x] 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.)
• [x] 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

• Create a Django Point Field
• Serialize it using GeoFeatureModelSerializer
• Check generated schema

class Location(models.Model):
    user = models.ForeignKey(User, on_delete=models.CASCADE, related_name='locations')
    city = models.CharField(max_length=128)
    state = models.CharField(max_length=64, null=True)
    country_code = models.CharField(max_length=2)
    country = models.CharField(max_length=64)
    point = models.PointField(null=True)

class LocationSerializer(GeoFeatureModelSerializer):
    class Meta:
        model = Location
        geo_field = "point"
        fields = ('city', 'state', 'country', 'point', 'tag')

GeoFeatureModelSerializer is from: https://github.com/openwisp/django-rest-framework-gis

Expected behavior

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [
      -123.0208,
      44.0464
    ]
  },
  "properties": {
    "city": "string",
    "state": "string",
    "country": "string",
  }
}

Actual behavior

{
  "city": "string",
  "state": "string",
  "country": "string",
  "point": "string",
}

Here, the serializer is generating some custom output using serializer fields. openapi generates schema directly from fields present in the serializer which will not work in these cases.

Proposed solution:

• Allow serializers to provide the schema
• If serializer has not provided any schema, generate schema directly from the serializer(current approach)

What I want from DRF: Provide a guideline/approach to override schema generation. I am open to raising a Pull request.
Once we have a solution, I will raise an issue in django-rest-framework-gis. This library will provide a custom schema.

[carltongibson]

django-rest-framework-gis should create an AutoSchema subclass that you would use to map GeoFeatureModelSerializer subclasses.

The simplest would look for a GeoFeatureModelSerializer in _map_serializer() and handle it, or hand off to super().

We'll promote _map_serializer() a public map_serializer() now I think.

I'll leave this open to track that for now.

[dhaval-mehta]

Many thanks for the prompt reply. In #6418, you proposed the same idea.
Rather than overriding entire AutoSchema, I think mixin with required overridden methods would be a better choice.

As of now, _map_serializer() is a private method. This should be overridden by any library because DRF can remove this method in any future release without any notice. It would be great if you can provide a solution which is future proof.

[carltongibson]

We'll promote _map_serializer() a public map_serializer() now I think.

Override _map_serializer() for now. We will make it public, as I said.

AutoSchema is not a big class. Mixins are overkill for this.

[carltongibson]

I've drafted the docs for this. I'm going to close it to keep my TODO list functioning.