def _map_model_field(self, model_field, direction):
assert isinstance(model_field, models.Field)
# to get a fully initialized serializer field we use DRF's own init logic
try:
field_cls, field_kwargs = serializers.ModelSerializer().build_field(
field_name=model_field.name,
info=get_field_info(model_field.model),
model_class=model_field.model,
nested_depth=0,
)
field = field_cls(**field_kwargs)
except: # noqa
field = None
# For some cases, the DRF init logic either breaks (custom field with internal type) or
# the resulting field is underspecified with regards to the schema (ReadOnlyField).
if field and not anyisinstance(field, [serializers.ReadOnlyField, serializers.ModelField]):
return self._map_serializer_field(field, direction)
elif isinstance(model_field, models.ForeignKey):
return self._map_model_field(model_field.target_field, direction)
elif hasattr(models, model_field.get_internal_type()):
# be graceful when the model field is not explicitly mapped to a serializer
internal_type = getattr(models, model_field.get_internal_type())
field_cls = serializers.ModelSerializer.serializer_field_mapping[internal_type]
return self._map_serializer_field(field_cls(), direction)
else:
error(
f'could not resolve model field "{model_field}". failed to resolve through '
f'serializer_field_mapping, get_internal_type(), or any override mechanism. '
f'defaulting to "string"'
)
return build_basic_type(OpenApiTypes.STR)
def _map_model_field(self, model_field, direction):
assert isinstance(model_field, models.Field)
# to get a fully initialized serializer field we use DRF's own init logic
try:
field_cls, field_kwargs = serializers.ModelSerializer(
).build_field(
field_name=model_field.name,
info=get_field_info(model_field.model),
model_class=model_field.model,
nested_depth=0,
)
field = field_cls(**field_kwargs)
except: # noqa
field = None
# For some cases, the DRF init logic either breaks (custom field with internal type) or
# the resulting field is underspecified with regards to the schema (ReadOnlyField).
if field and isinstance(field, serializers.PrimaryKeyRelatedField):
# special case handling only for _resolve_path_parameters() where neither queryset nor
# parent is set by build_field. patch in queryset as _map_serializer_field requires it
if not field.queryset:
field.queryset = model_field.related_model.objects.none()
return self._map_serializer_field(field, direction)
elif field and not anyisinstance(
field, [serializers.ReadOnlyField, serializers.ModelField]):
return self._map_serializer_field(field, direction)
elif isinstance(model_field, models.ForeignKey):
return self._map_model_field(model_field.target_field, direction)
elif hasattr(models, 'JSONField') and isinstance(
model_field, models.JSONField):
# fix for DRF==3.11 with django>=3.1 as it is not yet represented in the field_mapping
return build_basic_type(OpenApiTypes.OBJECT)
elif hasattr(models, model_field.get_internal_type()):
# be graceful when the model field is not explicitly mapped to a serializer
internal_type = getattr(models, model_field.get_internal_type())
field_cls = serializers.ModelSerializer.serializer_field_mapping.get(
internal_type)
if not field_cls:
warn(
f'model field "{model_field.get_internal_type()}" has no mapping in '
f'ModelSerializer. it may be a deprecated field. defaulting to "string"'
)
return build_basic_type(OpenApiTypes.STR)
return self._map_serializer_field(field_cls(), direction)
else:
error(
f'could not resolve model field "{model_field}". failed to resolve through '
f'serializer_field_mapping, get_internal_type(), or any override mechanism. '
f'defaulting to "string"')
return build_basic_type(OpenApiTypes.STR)
def _map_serializer_field(self, field, direction):
if has_override(field, 'field'):
override = get_override(field, 'field')
if is_basic_type(override):
return build_basic_type(override)
else:
return self._map_serializer_field(override, direction)
meta = self._get_serializer_field_meta(field)
serializer_field_extension = OpenApiSerializerFieldExtension.get_match(
field)
if serializer_field_extension:
schema = serializer_field_extension.map_serializer_field(
self, direction)
return append_meta(schema, meta)
# nested serializer
if isinstance(field, serializers.Serializer):
component = self.resolve_serializer(field, direction)
return append_meta(component.ref, meta) if component else None
# nested serializer with many=True gets automatically replaced with ListSerializer
if isinstance(field, serializers.ListSerializer):
if is_serializer(field.child):
component = self.resolve_serializer(field.child, direction)
return append_meta(build_array_type(component.ref),
meta) if component else None
else:
schema = self._map_serializer_field(field.child, direction)
return append_meta(build_array_type(schema), meta)
# Related fields.
if isinstance(field, serializers.ManyRelatedField):
schema = self._map_serializer_field(field.child_relation,
direction)
# remove hand-over initkwargs applying only to outer scope
schema.pop('description', None)
schema.pop('readOnly', None)
return append_meta(build_array_type(schema), meta)
if isinstance(field, serializers.PrimaryKeyRelatedField):
# read_only fields do not have a Manager by design. go around and get field
# from parent. also avoid calling Manager. __bool__ as it might be customized
# to hit the database.
if getattr(field, 'queryset', None) is not None:
model_field = field.queryset.model._meta.pk
else:
if isinstance(field.parent, serializers.ManyRelatedField):
model_field = field.parent.parent.Meta.model._meta.pk
else:
model_field = field.parent.Meta.model._meta.pk
# primary keys are usually non-editable (readOnly=True) and map_model_field correctly
# signals that attribute. however this does not apply in the context of relations.
schema = self._map_model_field(model_field, direction)
schema.pop('readOnly', None)
return append_meta(schema, meta)
if isinstance(field, serializers.StringRelatedField):
return append_meta(build_basic_type(OpenApiTypes.STR), meta)
if isinstance(field, serializers.SlugRelatedField):
return append_meta(build_basic_type(OpenApiTypes.STR), meta)
if isinstance(field, serializers.HyperlinkedIdentityField):
return append_meta(build_basic_type(OpenApiTypes.URI), meta)
if isinstance(field, serializers.HyperlinkedRelatedField):
return append_meta(build_basic_type(OpenApiTypes.URI), meta)
if isinstance(field, serializers.MultipleChoiceField):
return append_meta(
build_array_type(build_choice_field(field.choices)), meta)
if isinstance(field, serializers.ChoiceField):
return append_meta(build_choice_field(field.choices), meta)
if isinstance(field, serializers.ListField):
schema = build_array_type({})
# TODO check this
if not isinstance(field.child, _UnvalidatedField):
map_field = self._map_serializer_field(field.child, direction)
items = {"type": map_field.get('type')}
if 'format' in map_field:
items['format'] = map_field.get('format')
schema['items'] = items
return append_meta(schema, meta)
# DateField and DateTimeField type is string
if isinstance(field, serializers.DateField):
return append_meta(build_basic_type(OpenApiTypes.DATE), meta)
if isinstance(field, serializers.DateTimeField):
return append_meta(build_basic_type(OpenApiTypes.DATETIME), meta)
if isinstance(field, serializers.TimeField):
return append_meta(build_basic_type(OpenApiTypes.TIME), meta)
if isinstance(field, serializers.EmailField):
return append_meta(build_basic_type(OpenApiTypes.EMAIL), meta)
if isinstance(field, serializers.URLField):
return append_meta(build_basic_type(OpenApiTypes.URI), meta)
if isinstance(field, serializers.UUIDField):
return append_meta(build_basic_type(OpenApiTypes.UUID), meta)
if isinstance(field, serializers.DurationField):
return append_meta(build_basic_type(OpenApiTypes.STR), meta)
if isinstance(field, serializers.IPAddressField):
# TODO this might be a DRF bug. protocol is not propagated to serializer although it
# should have been. results in always 'both' (thus no format)
if 'ipv4' == field.protocol.lower():
schema = build_basic_type(OpenApiTypes.IP4)
elif 'ipv6' == field.protocol.lower():
schema = build_basic_type(OpenApiTypes.IP6)
else:
schema = build_basic_type(OpenApiTypes.STR)
return append_meta(schema, meta)
# DecimalField has multipleOf based on decimal_places
if isinstance(field, serializers.DecimalField):
if getattr(field, 'coerce_to_string',
api_settings.COERCE_DECIMAL_TO_STRING):
content = {
**build_basic_type(OpenApiTypes.STR), 'format': 'decimal'
}
else:
content = build_basic_type(OpenApiTypes.DECIMAL)
if field.max_whole_digits:
content['maximum'] = int(field.max_whole_digits * '9') + 1
content['minimum'] = -content['maximum']
self._map_min_max(field, content)
return append_meta(content, meta)
if isinstance(field, serializers.FloatField):
content = build_basic_type(OpenApiTypes.FLOAT)
self._map_min_max(field, content)
return append_meta(content, meta)
if isinstance(field, serializers.IntegerField):
content = build_basic_type(OpenApiTypes.INT)
self._map_min_max(field, content)
# 2147483647 is max for int32_size, so we use int64 for format
if int(content.get('maximum', 0)) > 2147483647 or int(
content.get('minimum', 0)) > 2147483647:
content['format'] = 'int64'
return append_meta(content, meta)
if isinstance(field, serializers.FileField):
if spectacular_settings.COMPONENT_SPLIT_REQUEST and direction == 'request':
content = build_basic_type(OpenApiTypes.BINARY)
else:
use_url = getattr(field, 'use_url',
api_settings.UPLOADED_FILES_USE_URL)
content = build_basic_type(
OpenApiTypes.URI if use_url else OpenApiTypes.STR)
return append_meta(content, meta)
if isinstance(field, serializers.SerializerMethodField):
method = getattr(field.parent, field.method_name)
return append_meta(self._map_response_type_hint(method), meta)
if anyisinstance(
field,
[serializers.BooleanField, serializers.NullBooleanField]):
return append_meta(build_basic_type(OpenApiTypes.BOOL), meta)
if isinstance(field, serializers.JSONField):
return append_meta(build_basic_type(OpenApiTypes.OBJECT), meta)
if anyisinstance(field,
[serializers.DictField, serializers.HStoreField]):
content = build_basic_type(OpenApiTypes.OBJECT)
if not isinstance(field.child, _UnvalidatedField):
content['additionalProperties'] = self._map_serializer_field(
field.child, direction)
return append_meta(content, meta)
if isinstance(field, serializers.CharField):
return append_meta(build_basic_type(OpenApiTypes.STR), meta)
if isinstance(field, serializers.ReadOnlyField):
# direct source from the serializer
assert field.source_attrs, f'ReadOnlyField "{field}" needs a proper source'
target = follow_field_source(field.parent.Meta.model,
field.source_attrs)
if callable(target):
schema = self._map_response_type_hint(target)
elif isinstance(target, models.Field):
schema = self._map_model_field(target, direction)
else:
assert False, f'ReadOnlyField target "{field}" must be property or model field'
return append_meta(schema, meta)
# DRF was not able to match the model field to an explicit SerializerField and therefore
# used its generic fallback serializer field that simply wraps the model field.
if isinstance(field, serializers.ModelField):
schema = self._map_model_field(field.model_field, direction)
return append_meta(schema, meta)
warn(
f'could not resolve serializer field "{field}". defaulting to "string"'
)
return append_meta(build_basic_type(OpenApiTypes.STR), meta)
def _map_serializer_field(self, method, field):
if hasattr(field, '_spectacular_annotation'):
if is_basic_type(field._spectacular_annotation):
return build_basic_type(field._spectacular_annotation)
else:
return self._map_serializer_field(
method, field._spectacular_annotation)
# nested serializer
if isinstance(field, serializers.Serializer):
return self.resolve_serializer(method, field).ref
# nested serializer with many=True gets automatically replaced with ListSerializer
if isinstance(field, serializers.ListSerializer):
return build_array_type(
self.resolve_serializer(method, field.child).ref)
# Related fields.
if isinstance(field, serializers.ManyRelatedField):
return build_array_type(
self._map_serializer_field(method, field.child_relation))
if isinstance(field, serializers.PrimaryKeyRelatedField):
# read_only fields do not have a Manager by design. go around and get field
# from parent. also avoid calling Manager. __bool__ as it might be customized
# to hit the database.
if getattr(field, 'queryset', None) is not None:
return self._map_model_field(field.queryset.model._meta.pk)
else:
model = field.parent.Meta.model
return self._map_model_field(
get_field_from_model(model, model.id))
if isinstance(field, serializers.StringRelatedField):
return build_basic_type(OpenApiTypes.STR)
if isinstance(field, serializers.SlugRelatedField):
return build_basic_type(OpenApiTypes.STR)
if isinstance(field, serializers.HyperlinkedIdentityField):
return build_basic_type(OpenApiTypes.URI)
if isinstance(field, serializers.HyperlinkedRelatedField):
return build_basic_type(OpenApiTypes.URI)
# ChoiceFields (single and multiple).
# Q:
# - Is 'type' required?
# - can we determine the TYPE of a choicefield?
if isinstance(field, serializers.MultipleChoiceField):
return build_array_type(self._map_choicefield(field))
if isinstance(field, serializers.ChoiceField):
return self._map_choicefield(field)
if isinstance(field, serializers.ListField):
schema = build_array_type({})
# TODO check this
if not isinstance(field.child, _UnvalidatedField):
map_field = self._map_serializer_field(method, field.child)
items = {"type": map_field.get('type')}
if 'format' in map_field:
items['format'] = map_field.get('format')
schema['items'] = items
return schema
# DateField and DateTimeField type is string
if isinstance(field, serializers.DateField):
return build_basic_type(OpenApiTypes.DATE)
if isinstance(field, serializers.DateTimeField):
return build_basic_type(OpenApiTypes.DATETIME)
if isinstance(field, serializers.EmailField):
return build_basic_type(OpenApiTypes.EMAIL)
if isinstance(field, serializers.URLField):
return build_basic_type(OpenApiTypes.URI)
if isinstance(field, serializers.UUIDField):
return build_basic_type(OpenApiTypes.UUID)
if isinstance(field, serializers.IPAddressField):
# TODO this might be a DRF bug. protocol is not propagated to serializer although it
# should have been. results in always 'both' (thus no format)
if 'ipv4' == field.protocol.lower():
return build_basic_type(OpenApiTypes.IP4)
elif 'ipv6' == field.protocol.lower():
return build_basic_type(OpenApiTypes.IP6)
else:
return build_basic_type(OpenApiTypes.STR)
# DecimalField has multipleOf based on decimal_places
if isinstance(field, serializers.DecimalField):
content = {'type': 'number'}
if field.decimal_places:
content['multipleOf'] = float('.' +
(field.decimal_places - 1) *
'0' + '1')
if field.max_whole_digits:
content['maximum'] = int(field.max_whole_digits * '9') + 1
content['minimum'] = -content['maximum']
self._map_min_max(field, content)
return content
if isinstance(field, serializers.FloatField):
content = build_basic_type(OpenApiTypes.FLOAT)
self._map_min_max(field, content)
return content
if isinstance(field, serializers.IntegerField):
content = build_basic_type(OpenApiTypes.INT)
self._map_min_max(field, content)
# 2147483647 is max for int32_size, so we use int64 for format
if int(content.get('maximum', 0)) > 2147483647 or int(
content.get('minimum', 0)) > 2147483647:
content['format'] = 'int64'
return content
if isinstance(field, serializers.FileField):
# TODO returns filename. but does it accept binary data on upload?
return build_basic_type(OpenApiTypes.STR)
if isinstance(field, serializers.SerializerMethodField):
method = getattr(field.parent, field.method_name)
return self._map_type_hint(method)
if isinstance(field, serializers.BooleanField):
return build_basic_type(OpenApiTypes.BOOL)
if anyisinstance(field, [
serializers.JSONField, serializers.DictField,
serializers.HStoreField
]):
return build_basic_type(OpenApiTypes.OBJECT)
if isinstance(field, serializers.CharField):
return build_basic_type(OpenApiTypes.STR)
if isinstance(field, serializers.ReadOnlyField):
# direct source from the serializer
assert field.source_attrs, 'ReadOnlyField needs a proper source'
target = follow_field_source(field.parent.Meta.model,
field.source_attrs)
if callable(target):
return self._map_type_hint(target)
elif isinstance(target, models.Field):
return self._map_model_field(target)
warn(
f'could not resolve serializer field {field}. defaulting to "string"'
)
return build_basic_type(OpenApiTypes.STR)
