Merge branch 'pr1491'

tfranzel · tfranzel · commit ef99f6d4da10 · 2026-04-14T14:19:40.000+03:00
diff --git a/drf_spectacular/plumbing.py b/drf_spectacular/plumbing.py
@@ -232,6 +232,9 @@ def get_view_model(view, emit_warnings=True):
 
 def get_doc(obj) -> str:
     """ get doc string with fallback on obj's base classes (ignoring DRF documentation). """
+    if spectacular_settings.DISABLE_DOCSTRING_DESCRIPTIONS:
+        return ''
+
     def post_cleanup(doc: str) -> str:
         # also clean up trailing whitespace for each line
         return '\n'.join(line.rstrip() for line in doc.rstrip().split('\n'))
diff --git a/drf_spectacular/settings.py b/drf_spectacular/settings.py
@@ -126,6 +126,10 @@
 
     # function that returns a list of all classes that should be excluded from doc string extraction
     'GET_LIB_DOC_EXCLUDES': 'drf_spectacular.plumbing.get_lib_doc_excludes',
+    # Stops docstrings of views, serializers and their methods, from being used as
+    # description strings in the schema. Useful when docstrings are for internal use
+    # only and should not be exposed in the API documentation.
+    'DISABLE_DOCSTRING_DESCRIPTIONS': False,
 
     # Function that returns a mocked request for view processing. For CLI usage
     # original_request will be None.
diff --git a/tests/test_plumbing.py b/tests/test_plumbing.py
@@ -5,6 +5,7 @@
 import typing
 from datetime import datetime
 from enum import Enum
+from unittest import mock
 
 if sys.version_info >= (3, 8):
     from typing import TypedDict
@@ -467,3 +468,52 @@ class MyClass(typing.Generic[T]):
 
     doc = get_doc(MyClass)
     assert doc == ""
+
+
+@pytest.mark.parametrize('disable', [False, True])
+def test_get_doc_with_class_docstring(disable):
+    class MyClass:
+        """a docstring"""
+
+    with mock.patch(
+        "drf_spectacular.settings.spectacular_settings.DISABLE_DOCSTRING_DESCRIPTIONS",
+        disable,
+    ):
+        doc = get_doc(MyClass)
+        if disable:
+            assert doc == ""
+        else:
+            assert doc == "a docstring"
+
+
+@pytest.mark.parametrize('disable', [False, True])
+def test_get_doc_with_function_docstring(disable):
+    def my_func():
+        """a docstring"""
+
+    with mock.patch(
+        "drf_spectacular.settings.spectacular_settings.DISABLE_DOCSTRING_DESCRIPTIONS",
+        disable,
+    ):
+        doc = get_doc(my_func)
+        if disable:
+            assert doc == ""
+        else:
+            assert doc == "a docstring"
+
+
+@pytest.mark.parametrize('disable', [False, True])
+def test_get_doc_with_method_docstring(disable):
+    class MyClass:
+        def my_method(self):
+            """a docstring"""
+
+    with mock.patch(
+        "drf_spectacular.settings.spectacular_settings.DISABLE_DOCSTRING_DESCRIPTIONS",
+        disable,
+    ):
+        doc = get_doc(MyClass().my_method)
+        if disable:
+            assert doc == ""
+        else:
+            assert doc == "a docstring"
diff --git a/tests/test_regressions.py b/tests/test_regressions.py
@@ -2574,6 +2574,46 @@ def create(self, request):
     )
 
 
+@pytest.mark.parametrize('disable', [False, True])
+def test_disable_docstring_descriptions(no_warnings, disable):
+    class XSerializer(serializers.Serializer):
+        """serializer docstring"""
+        field = serializers.CharField()
+        field_method = serializers.SerializerMethodField()
+
+        def get_field_method(self) -> str:
+            """method field docstring"""
+            return ''  # pragma: no cover
+
+    class XViewset(viewsets.ModelViewSet):
+        """view class docstring"""
+        serializer_class = XSerializer
+        queryset = SimpleModel.objects.none()
+
+        def retrieve(self, request):
+            """action docstring"""
+            pass  # pragma: no cover
+
+    with mock.patch(
+        'drf_spectacular.settings.spectacular_settings.DISABLE_DOCSTRING_DESCRIPTIONS', disable
+    ):
+        schema = generate_schema('/x', XViewset)
+
+    if disable:
+        assert 'description' not in schema['paths']['/x/']['get']
+        assert 'description' not in schema['paths']['/x/{id}/']['get']
+        assert 'description' not in schema['components']['schemas']['X']
+        assert 'description' not in schema['components']['schemas']['X']['properties']['field_method']
+    else:
+        assert schema['paths']['/x/']['get']['description'] == 'view class docstring'
+        assert schema['paths']['/x/{id}/']['get']['description'] == 'action docstring'
+        assert schema['components']['schemas']['X']['description'] == 'serializer docstring'
+        assert (
+            schema['components']['schemas']['X']['properties']['field_method']['description']
+            == 'method field docstring'
+        )
+
+
 @pytest.mark.parametrize('list_variation', [
     serializers.ListField, serializers.ListSerializer
 ])
