Deprecated built-in schema generation.

* To be removed in v25.
* Use drf-spectacular.

Closes #1432. Closes #1573.

Author: carltongibson

CHANGES.rst

@@ -1,3 +1,17 @@
+Version 23.2 (UNRELEASED)
+-------------------------
+
+* Deprecated the schema generation methods of the DRF related ``DjangoFilterBackend``.
+  These will be removed in version 25.1.
+
+  You should use `drf-spectacular <https://drf-spectacular.readthedocs.io/en/latest/>`_
+  for generating OpenAPI schemas with DRF.
+
+* In addition, stopped testing against the (very old now) ``coreapi`` schema generation.
+  These methods should continue to work if you're using them until v25.1, but
+  ``coreapi`` is no longer maintained, and is raising warnings against the current
+  versions of Python. To workaround this is not worth the effort at this point.
+
 Version 23.1 (2023-3-26)
 ------------------------
 

django_filters/__init__.py

@@ -29,3 +29,11 @@ def parse_version(version):
 
 
 VERSION = parse_version(__version__)
+
+
+
+assert VERSION < (25,0), "Remove deprecated code"
+
+
+class RemovedInDjangoFilter25Warning(DeprecationWarning):
+    pass

django_filters/rest_framework/backends.py

@@ -93,6 +93,11 @@ def get_schema_fields(self, view):
         # This is not compatible with widgets where the query param differs from the
         # filter's attribute name. Notably, this includes `MultiWidget`, where query
         # params will be of the format `<name>_0`, `<name>_1`, etc...
+        from django_filters import RemovedInDjangoFilter25Warning
+        warnings.warn(
+            "Built-in schema generation is deprecated. Use drf-spectacular.",
+            category=RemovedInDjangoFilter25Warning,
+        )
         assert (
             compat.coreapi is not None
         ), "coreapi must be installed to use `get_schema_fields()`"
@@ -125,6 +130,11 @@ def get_schema_fields(self, view):
         )
 
     def get_schema_operation_parameters(self, view):
+        from django_filters import RemovedInDjangoFilter25Warning
+        warnings.warn(
+            "Built-in schema generation is deprecated. Use drf-spectacular.",
+            category=RemovedInDjangoFilter25Warning,
+        )
         try:
             queryset = view.get_queryset()
         except Exception:

requirements/test-ci.txt

@@ -1,5 +1,4 @@
 markdown
-coreapi
 django-crispy-forms
 
 coverage

tests/rest_framework/test_backends.py

@@ -3,11 +3,11 @@
 
 from django.db.models import BooleanField
 from django.test import TestCase
-from django.test.utils import override_settings
+from django.test.utils import ignore_warnings, override_settings
 from rest_framework import generics, serializers
 from rest_framework.test import APIRequestFactory
 
-from django_filters import compat, filters
+from django_filters import RemovedInDjangoFilter25Warning, compat, filters
 from django_filters.rest_framework import DjangoFilterBackend, FilterSet, backends
 
 from ..models import Article
@@ -245,13 +245,15 @@ class View(FilterClassRootView):
 
 
 class GetSchemaOperationParametersTests(TestCase):
+    @ignore_warnings(category=RemovedInDjangoFilter25Warning)
     def test_get_operation_parameters_with_filterset_fields_list(self):
         backend = DjangoFilterBackend()
         fields = backend.get_schema_operation_parameters(FilterFieldsRootView())
         fields = [f["name"] for f in fields]
 
         self.assertEqual(fields, ["decimal", "date"])
 
+    @ignore_warnings(category=RemovedInDjangoFilter25Warning)
     def test_get_operation_parameters_with_filterset_fields_list_with_choices(self):
         backend = DjangoFilterBackend()
         fields = backend.get_schema_operation_parameters(CategoryItemView())
@@ -269,6 +271,12 @@ def test_get_operation_parameters_with_filterset_fields_list_with_choices(self):
             ],
         )
 
+    def test_deprecation_warning(self):
+        backend = DjangoFilterBackend()
+        msg = "Built-in schema generation is deprecated. Use drf-spectacular."
+        with self.assertWarnsMessage(RemovedInDjangoFilter25Warning, msg):
+            backend.get_schema_operation_parameters(FilterFieldsRootView())
+
 
 class TemplateTests(TestCase):
     def test_backend_output(self):
@@ -407,6 +415,7 @@ def test_to_html_none_filter_class(self):
         html = self.backend.to_html(mock.Mock(), mock.Mock(), mock.Mock())
         self.assertIsNone(html)
 
+    @ignore_warnings(category=RemovedInDjangoFilter25Warning)
     def test_get_schema_operation_parameters_userwarning(self):
         with self.assertWarns(UserWarning):
             view = mock.Mock()