Hard coded domain/url in get_paginated_response_schema

[SteinRobert]

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.)

I noticed that the domain and url within the schema of a response is hard coded (https://github.com/encode/django-rest-framework/blob/master/rest_framework/pagination.py#L240).
I was thinking about making the example string somehow configurable. Not sure how though. Maybe a Django setting?

PAGINATION_EXAMPLE_NEXT= "https://mydomain.com/api/url?{offset_param}=400&{limit_param}=100"
PAGINATION_EXAMPLE_PREV= "https://mydomain.com/api/url??{offset_param}=400&{limit_param}=100"

However, this may not be flexible enough when applying a pagination class to different viewsets.

So maybe we could expand the views by some parameters? Or even getter methods.

class SomeModelViewSet(viewsets.ModelViewSet):
  schema_example_domain = "https://mydomain.com"
  schema_example_url = reverse_lazy("app:view-name")

  def get_schema_example_domain(self):
    return self.schema_example_domain

  def get_schema_example_url(self):
    return self.schema_example_url

It could be passed into get_paginated_response_schema when called (https://github.com/encode/django-rest-framework/blob/master/rest_framework/schemas/openapi.py#L665):

response_schema = paginator.get_paginated_response_schema(response_schema, self.view)

This way the domain and the url would be configurable. We could still fallback to the default.

Any thoughts?

Steps to reproduce

Generate a schema with a list view.

Expected behavior

The response should look like this:

responses:
  '200':
    content:
      application/json:
        schema:
          type: object
          properties:
            count:
              type: integer
              example: 123
            next:
              type: string
              nullable: true
              format: uri
              example: http://my.domain.com/my/url/path/?offset=400&limit=100
            previous:
              type: string
              nullable: true
              format: uri
              example: http://my.domain.com/my/url/path/?offset=200&limit=100
            results:
              type: array
              items:
                $ref: '#/components/schemas/Model'
          description: ''

Actual behavior

The response looks somehow like the following:

responses:
  '200':
    content:
      application/json:
        schema:
          type: object
          properties:
            count:
              type: integer
              example: 123
            next:
              type: string
              nullable: true
              format: uri
              example: http://api.example.org/accounts/?offset=400&limit=100
            previous:
              type: string
              nullable: true
              format: uri
              example: http://api.example.org/accounts/?offset=200&limit=100
            results:
              type: array
              items:
                $ref: '#/components/schemas/Model'
          description: ''

[SteinRobert]

I was just having a closer look at the design of the schema generation within DRF. May the following suggestion is more appropriate.

1. Allow to define protocol, domain within AutoSchema.
2. Both protocol and domain as well as the path are passed into the get_paginated_response_schema.

This way schema generation is still isolated within the AutoSchema class, without polluting APIView or the GenericAPIView or even any Pagination class.

[carltongibson]

Hi @SteinRobert.

This way schema generation is still isolated within the AutoSchema class, without polluting APIView or the GenericAPIView or even any Pagination class.

This would be the way to go here. Attributes on AutoSchema rather than anywhere else.

I'm guessing though that what really needed here is access to the SchemaGenerator.url https://www.django-rest-framework.org/api-guide/schemas/#schemagenerator — That was you'd pass it once, and then it could be reused in this kind of case. 🤔

This would need the top-level get_operation() (and probably get_components()) to accept a reference to the generator I suppose.

In the meantime I'd subclass AutoSchema to add the parameters, to at least get you up and running. (Looking at the PR, do you really need protocol and domain as separate parameters? Would base_url not do?)

I guess this seems reasonable in principle to me.

[SteinRobert]

I rebased the PR (#7657) onto the current master branch. Tests are passing now. I would love to hear your thoughts about it guys :)