From 92383cf4ba91e209f75a161b66e4c174338e706c Mon Sep 17 00:00:00 2001 From: Reupen Shah Date: Tue, 3 Sep 2019 14:25:44 +0100 Subject: [PATCH] Add support for pagination in OpenAPI response schemas (#6867) Refs #6846 This provides a way for pagination classes to add pagination properties (`count`, `next`, `results` etc.) to OpenAPI response schemas. A new method `get_paginated_response_schema()` has been added to `BasePagination`. This method is intended to mirror `get_paginated_response()` (which takes a `list` and wraps it in a `dict`). Hence, `get_paginated_response_schema()` takes an unpaginated response schema (of type `array`) and wraps that with a schema object of type `object` containing the relevant properties that the pagination class adds to responses. The default implementation of `BasePagination.get_paginated_response_schema()` simply passes the schema through unmodified, for backwards compatibility. --- rest_framework/pagination.py | 59 ++++++++++++++++++++ rest_framework/schemas/openapi.py | 15 ++++-- tests/schemas/test_openapi.py | 66 ++++++++++++++++++++++- tests/test_pagination.py | 89 +++++++++++++++++++++++++++++++ 4 files changed, 225 insertions(+), 4 deletions(-) diff --git a/rest_framework/pagination.py b/rest_framework/pagination.py index a68e8ab1288..1a1ba2f6576 100644 --- a/rest_framework/pagination.py +++ b/rest_framework/pagination.py @@ -138,6 +138,9 @@ def paginate_queryset(self, queryset, request, view=None): # pragma: no cover def get_paginated_response(self, data): # pragma: no cover raise NotImplementedError('get_paginated_response() must be implemented.') + def get_paginated_response_schema(self, schema): + return schema + def to_html(self): # pragma: no cover raise NotImplementedError('to_html() must be implemented to display page controls.') @@ -222,6 +225,26 @@ def get_paginated_response(self, data): ('results', data) ])) + def get_paginated_response_schema(self, schema): + return { + 'type': 'object', + 'properties': { + 'count': { + 'type': 'integer', + 'example': 123, + }, + 'next': { + 'type': 'string', + 'nullable': True, + }, + 'previous': { + 'type': 'string', + 'nullable': True, + }, + 'results': schema, + }, + } + def get_page_size(self, request): if self.page_size_query_param: try: @@ -369,6 +392,26 @@ def get_paginated_response(self, data): ('results', data) ])) + def get_paginated_response_schema(self, schema): + return { + 'type': 'object', + 'properties': { + 'count': { + 'type': 'integer', + 'example': 123, + }, + 'next': { + 'type': 'string', + 'nullable': True, + }, + 'previous': { + 'type': 'string', + 'nullable': True, + }, + 'results': schema, + }, + } + def get_limit(self, request): if self.limit_query_param: try: @@ -840,6 +883,22 @@ def get_paginated_response(self, data): ('results', data) ])) + def get_paginated_response_schema(self, schema): + return { + 'type': 'object', + 'properties': { + 'next': { + 'type': 'string', + 'nullable': True, + }, + 'previous': { + 'type': 'string', + 'nullable': True, + }, + 'results': schema, + }, + } + def get_html_context(self): return { 'previous_url': self.get_previous_link(), diff --git a/rest_framework/schemas/openapi.py b/rest_framework/schemas/openapi.py index 0af7510cdee..343d0b6247b 100644 --- a/rest_framework/schemas/openapi.py +++ b/rest_framework/schemas/openapi.py @@ -206,11 +206,10 @@ def _get_pagination_parameters(self, path, method): if not is_list_view(path, method, view): return [] - pagination = getattr(view, 'pagination_class', None) - if not pagination: + paginator = self._get_pagninator() + if not paginator: return [] - paginator = view.pagination_class() return paginator.get_schema_operation_parameters(view) def _map_field(self, field): @@ -423,6 +422,13 @@ def _map_field_validators(self, validators, schema): schema['maximum'] = int(digits * '9') + 1 schema['minimum'] = -schema['maximum'] + def _get_pagninator(self): + pagination_class = getattr(self.view, 'pagination_class', None) + if pagination_class: + return pagination_class() + + return None + def _get_serializer(self, method, path): view = self.view @@ -489,6 +495,9 @@ def _get_responses(self, path, method): 'type': 'array', 'items': item_schema, } + paginator = self._get_pagninator() + if paginator: + response_schema = paginator.get_paginated_response_schema(response_schema) else: response_schema = item_schema diff --git a/tests/schemas/test_openapi.py b/tests/schemas/test_openapi.py index 78a5609dac4..e0fe3c9abe9 100644 --- a/tests/schemas/test_openapi.py +++ b/tests/schemas/test_openapi.py @@ -264,6 +264,58 @@ class View(generics.GenericAPIView): }, } + def test_paginated_list_response_body_generation(self): + """Test that pagination properties are added for a paginated list view.""" + path = '/' + method = 'GET' + + class Pagination(pagination.BasePagination): + def get_paginated_response_schema(self, schema): + return { + 'type': 'object', + 'item': schema, + } + + class ItemSerializer(serializers.Serializer): + text = serializers.CharField() + + class View(generics.GenericAPIView): + serializer_class = ItemSerializer + pagination_class = Pagination + + view = create_view( + View, + method, + create_request(path), + ) + inspector = AutoSchema() + inspector.view = view + + responses = inspector._get_responses(path, method) + assert responses == { + '200': { + 'description': '', + 'content': { + 'application/json': { + 'schema': { + 'type': 'object', + 'item': { + 'type': 'array', + 'items': { + 'properties': { + 'text': { + 'type': 'string', + }, + }, + 'required': ['text'], + }, + }, + }, + }, + }, + }, + } + def test_delete_response_body_generation(self): """Test that a view's delete method generates a proper response body schema.""" path = '/{id}/' @@ -288,15 +340,27 @@ class View(generics.DestroyAPIView): } def test_retrieve_response_body_generation(self): - """Test that a list of properties is returned for retrieve item views.""" + """ + Test that a list of properties is returned for retrieve item views. + + Pagination properties should not be added as the view represents a single item. + """ path = '/{id}/' method = 'GET' + class Pagination(pagination.BasePagination): + def get_paginated_response_schema(self, schema): + return { + 'type': 'object', + 'item': schema, + } + class ItemSerializer(serializers.Serializer): text = serializers.CharField() class View(generics.GenericAPIView): serializer_class = ItemSerializer + pagination_class = Pagination view = create_view( View, diff --git a/tests/test_pagination.py b/tests/test_pagination.py index 11fd6844dfb..cd84c815161 100644 --- a/tests/test_pagination.py +++ b/tests/test_pagination.py @@ -259,6 +259,37 @@ def test_invalid_page(self): with pytest.raises(exceptions.NotFound): self.paginate_queryset(request) + def test_get_paginated_response_schema(self): + unpaginated_schema = { + 'type': 'object', + 'item': { + 'properties': { + 'test-property': { + 'type': 'integer', + }, + }, + }, + } + + assert self.pagination.get_paginated_response_schema(unpaginated_schema) == { + 'type': 'object', + 'properties': { + 'count': { + 'type': 'integer', + 'example': 123, + }, + 'next': { + 'type': 'string', + 'nullable': True, + }, + 'previous': { + 'type': 'string', + 'nullable': True, + }, + 'results': unpaginated_schema, + }, + } + class TestPageNumberPaginationOverride: """ @@ -535,6 +566,37 @@ def test_max_limit(self): assert content.get('next') == next_url assert content.get('previous') == prev_url + def test_get_paginated_response_schema(self): + unpaginated_schema = { + 'type': 'object', + 'item': { + 'properties': { + 'test-property': { + 'type': 'integer', + }, + }, + }, + } + + assert self.pagination.get_paginated_response_schema(unpaginated_schema) == { + 'type': 'object', + 'properties': { + 'count': { + 'type': 'integer', + 'example': 123, + }, + 'next': { + 'type': 'string', + 'nullable': True, + }, + 'previous': { + 'type': 'string', + 'nullable': True, + }, + 'results': unpaginated_schema, + }, + } + class CursorPaginationTestsMixin: @@ -834,6 +896,33 @@ def test_cursor_pagination_with_page_size_negative(self): assert current == [1, 1, 1, 1, 1] assert next == [1, 2, 3, 4, 4] + def test_get_paginated_response_schema(self): + unpaginated_schema = { + 'type': 'object', + 'item': { + 'properties': { + 'test-property': { + 'type': 'integer', + }, + }, + }, + } + + assert self.pagination.get_paginated_response_schema(unpaginated_schema) == { + 'type': 'object', + 'properties': { + 'next': { + 'type': 'string', + 'nullable': True, + }, + 'previous': { + 'type': 'string', + 'nullable': True, + }, + 'results': unpaginated_schema, + }, + } + class TestCursorPagination(CursorPaginationTestsMixin): """