Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

If available, use docstrings from properties for field descriptions #698

Closed
wants to merge 1 commit into from
Closed

If available, use docstrings from properties for field descriptions #698

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 13 additions & 2 deletions drf_spectacular/openapi.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
import copy
import functools
import inspect
import re
import typing
from collections import defaultdict
Expand Down Expand Up @@ -1030,14 +1032,23 @@ def _map_response_type_hint(self, method):
if isinstance(hint, dict):
return hint

meta = {}
if not (
# partial does not produce helpful docstrings:
isinstance(method, functools.partial)
):
docstring = getattr(method, '__doc__', None)
if docstring:
meta['description'] = inspect.cleandoc(docstring)
try:
return resolve_type_hint(hint)
schema = resolve_type_hint(hint)
except UnableToProceedError:
warn(
f'unable to resolve type hint for function "{method.__name__}". Consider '
f'using a type hint or @extend_schema_field. Defaulting to string.'
)
return build_basic_type(OpenApiTypes.STR)
schema = build_basic_type(OpenApiTypes.STR)
return append_meta(schema, meta)

def _get_paginator(self):
pagination_class = getattr(self.view, 'pagination_class', None)
Expand Down
3 changes: 3 additions & 0 deletions tests/test_fields.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,9 @@ def __init__(self, instance):

@property
def calculated(self) -> int:
"""
My calculated property
"""
return self._instance.field_int

@property
Expand Down
7 changes: 7 additions & 0 deletions tests/test_fields.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,33 +178,40 @@ components:
additionalProperties: {}
field_sub_object_calculated:
type: integer
description: My calculated property
readOnly: true
field_sub_object_nested_calculated:
type: integer
description: My calculated property
readOnly: true
field_sub_object_model_int:
type: integer
readOnly: true
field_sub_object_cached_calculated:
type: integer
description: My calculated property
readOnly: true
field_sub_object_cached_nested_calculated:
type: integer
description: My calculated property
readOnly: true
field_sub_object_cached_model_int:
type: integer
readOnly: true
field_sub_object_py_cached_calculated:
type: integer
description: My calculated property
readOnly: true
field_sub_object_py_cached_nested_calculated:
type: integer
description: My calculated property
readOnly: true
field_sub_object_py_cached_model_int:
type: integer
readOnly: true
field_optional_sub_object_calculated:
type: integer
description: My calculated property
readOnly: true
nullable: true
field_sub_object_optional_int:
Expand Down