Merge pull request #371 from City-of-Turku/feature/services-api-docum…

…entation

Feature/services api documentation

services/api.py

@@ -15,6 +15,11 @@
 from django.utils import timezone, translation
 from django.utils.module_loading import import_string
 from django_filters.rest_framework import DjangoFilterBackend
+from drf_spectacular.utils import (
+ extend_schema,
+ extend_schema_field,
+ extend_schema_serializer,
+)
 from modeltranslation.translator import NotRegistered, translator
 from mptt.utils import drilldown_tree_for_node
 from munigeo import api as munigeo_api
@@ -41,6 +46,32 @@
  UnitServiceDetails,
 )
 from services.models.unit import ORGANIZER_TYPES, PROVIDER_TYPES
+from services.open_api_parameters import (
+ ACCESSIBILITY_DESCRIPTION_PARAMETER,
+ ANCESTOR_ID_PARAMETER,
+ BBOX_PARAMETER,
+ BUILDING_NUMBER_PARAMETER,
+ CITY_AS_DEPARTMENT_PARAMETER,
+ DATE_PARAMETER,
+ DISTANCE_PARAMETER,
+ DIVISION_TYPE_PARAMETER,
+ GEOMETRY_PARAMETER,
+ ID_PARAMETER,
+ INPUT_PARAMETER,
+ LATITUDE_PARAMETER,
+ LEVEL_PARAMETER,
+ LONGITUDE_PARAMETER,
+ MUNICIPALITY_PARAMETER,
+ OCD_ID_PARAMETER,
+ OCD_MUNICIPALITY_PARAMETER,
+ ORGANIZATION_PARAMETER,
+ ORIGIN_ID_PARAMETER,
+ PROVIDER_TYPE_NOT_PARAMETER,
+ PROVIDER_TYPE_PARAMETER,
+ STREET_PARAMETER,
+ UNIT_GEOMETRY_3D_PARAMETER,
+ UNIT_GEOMETRY_PARAMETER,
+)
 from services.utils import check_valid_concrete_field
 from services.utils.geocode_address import geocode_address
 
@@ -68,6 +99,17 @@ def register_view(klass, name, basename=None):
 logger = logging.getLogger(__name__)
 
 
+class TranslationsSerializer(serializers.Serializer):
+ fi = serializers.CharField(required=False)
+ sv = serializers.CharField(required=False)
+ en = serializers.CharField(required=False)
+
+
+@extend_schema_field(TranslationsSerializer)
+class TranslationsField(serializers.CharField):
+ pass
+
+
 class MPTTModelSerializer(serializers.ModelSerializer):
  def __init__(self, *args, **kwargs):
  super(MPTTModelSerializer, self).__init__(*args, **kwargs)
@@ -186,6 +228,13 @@ def to_representation(self, obj):
  return ret
 
 
+class ServicesTranslatedModelSerializer(TranslatedModelSerializer):
+ def __init__(self, *args, **kwargs):
+ super(ServicesTranslatedModelSerializer, self).__init__(*args, **kwargs)
+ for field_name in self.translated_fields:
+ self.fields[field_name] = TranslationsField()
+
+
 def root_services(services):
  tree_ids = set(s.tree_id for s in services)
  return map(
@@ -250,7 +299,7 @@ def to_representation(self, obj):
 
 
 class DepartmentSerializer(
- TranslatedModelSerializer, MPTTModelSerializer, JSONAPISerializer
+ ServicesTranslatedModelSerializer, MPTTModelSerializer, JSONAPISerializer
 ):
  id = serializers.SerializerMethodField("get_uuid")
  parent = serializers.SerializerMethodField()
@@ -272,7 +321,7 @@ def get_parent(self, obj):
 
 
 class ServiceNodeSerializer(
- TranslatedModelSerializer, MPTTModelSerializer, JSONAPISerializer
+ ServicesTranslatedModelSerializer, MPTTModelSerializer, JSONAPISerializer
 ):
  children = serializers.PrimaryKeyRelatedField(many=True, read_only=True)
 
@@ -326,7 +375,7 @@ class Meta:
  )
 
 
-class ServiceSerializer(TranslatedModelSerializer, JSONAPISerializer):
+class ServiceSerializer(ServicesTranslatedModelSerializer, JSONAPISerializer):
  def to_representation(self, obj):
  ret = super(ServiceSerializer, self).to_representation(obj)
  ret["unit_count"] = {"municipality": {}}
@@ -368,7 +417,7 @@ class Meta:
  fields = ["name", "root_service_node"]
 
 
-class ServiceDetailsSerializer(TranslatedModelSerializer, JSONAPISerializer):
+class ServiceDetailsSerializer(ServicesTranslatedModelSerializer, JSONAPISerializer):
  def to_representation(self, obj):
  ret = super(ServiceDetailsSerializer, self).to_representation(obj)
  service_data = RelatedServiceSerializer(obj.service).data
@@ -472,7 +521,9 @@ def choicefield_string(choices, key, obj):
  return None
 
 
-class UnitConnectionSerializer(TranslatedModelSerializer, serializers.ModelSerializer):
+class UnitConnectionSerializer(
+ ServicesTranslatedModelSerializer, serializers.ModelSerializer
+):
  section_type = serializers.SerializerMethodField()
 
  class Meta:
@@ -491,7 +542,9 @@ class UnitConnectionViewSet(viewsets.ReadOnlyModelViewSet):
 register_view(UnitConnectionViewSet, "unit_connection")
 
 
-class UnitEntranceSerializer(TranslatedModelSerializer, munigeo_api.GeoModelSerializer):
+class UnitEntranceSerializer(
+ ServicesTranslatedModelSerializer, munigeo_api.GeoModelSerializer
+):
  location = serializers.SerializerMethodField()
 
  class Meta:
@@ -502,7 +555,11 @@ def get_location(self, obj):
  return munigeo_api.geom_to_json(obj.location, self.srs)
 
 
-class UnitEntranceViewSet(munigeo_api.GeoModelAPIView, viewsets.ReadOnlyModelViewSet):
+class UnitEntranceViewSet(
+ ServicesTranslatedModelSerializer,
+ munigeo_api.GeoModelAPIView,
+ viewsets.ReadOnlyModelViewSet,
+):
  queryset = UnitEntrance.objects.all()
  serializer_class = UnitEntranceSerializer
 
@@ -532,6 +589,7 @@ class Meta:
  exclude = ["unit", "id"]
 
 
+@extend_schema(parameters=[ID_PARAMETER, ANCESTOR_ID_PARAMETER])
 class ServiceNodeViewSet(JSONAPIViewSet, viewsets.ReadOnlyModelViewSet):
  queryset = ServiceNode.objects.all()
  serializer_class = ServiceNodeSerializer
@@ -559,6 +617,7 @@ def get_queryset(self):
 register_view(ServiceNodeViewSet, "service_node")
 
 
+@extend_schema(parameters=[ID_PARAMETER])
 class ServiceViewSet(JSONAPIViewSet, viewsets.ReadOnlyModelViewSet):
  queryset = Service.objects.all()
  serializer_class = ServiceSerializer
@@ -587,7 +646,7 @@ def get_queryset(self):
 
 
 class UnitSerializer(
- TranslatedModelSerializer, munigeo_api.GeoModelSerializer, JSONAPISerializer
+ ServicesTranslatedModelSerializer, munigeo_api.GeoModelSerializer, JSONAPISerializer
 ):
  connections = UnitConnectionSerializer(many=True)
  entrances = UnitEntranceSerializer(many=True)
@@ -749,6 +808,13 @@ def to_representation(self, obj):
  elif "geometry" in ret:
  del ret["geometry"]
 
+ if qparams.get("geometry_3d", "").lower() in ("true", "1"):
+ geom = obj.geometry_3d
+ if geom:
+ ret["geometry_3d"] = munigeo_api.geom_to_json(geom, self.srs)
+ elif "geometry_3d" in ret:
+ del ret["geometry_3d"]
+
  if qparams.get("accessibility_description", "").lower() in ("true", "1"):
  ret["accessibility_description"] = shortcomings.accessibility_description
  return ret
@@ -812,6 +878,20 @@ def render(self, data, media_type=None, renderer_context=None):
  return render_to_string("kml.xml", resp)
 
 
+@extend_schema(
+ parameters=[
+ ACCESSIBILITY_DESCRIPTION_PARAMETER,
+ ID_PARAMETER,
+ OCD_MUNICIPALITY_PARAMETER,
+ ORGANIZATION_PARAMETER,
+ CITY_AS_DEPARTMENT_PARAMETER,
+ PROVIDER_TYPE_PARAMETER,
+ PROVIDER_TYPE_NOT_PARAMETER,
+ LEVEL_PARAMETER,
+ UNIT_GEOMETRY_PARAMETER,
+ UNIT_GEOMETRY_3D_PARAMETER,
+ ]
+)
 class UnitViewSet(
  munigeo_api.GeoModelAPIView, JSONAPIViewSet, viewsets.ReadOnlyModelViewSet
 ):
@@ -846,6 +926,12 @@ def get_queryset(self):
  id_list = filters["id"].split(",")
  queryset = queryset.filter(id__in=id_list)
 
+ for f in filters:
+ if f.startswith("extra__"):
+ queryset = queryset.filter(
+ **{f: int(filters[f]) if filters[f].isnumeric() else filters[f]}
+ )
+
  if "municipality" in filters:
  val = filters["municipality"].lower().strip()
  if len(val) > 0:
@@ -866,8 +952,18 @@ def get_queryset(self):
 
  queryset = queryset.filter(muni_sq)
 
- if "city_as_department" in filters:
- val = filters["city_as_department"].lower().strip()
+ if "organization" in filters or "city_as_department" in filters:
+ val = (
+ filters["organization"].lower().strip()
+ if "organization" in filters
+ else ""
+ )
+ if len(val) == 0:
+ val = (
+ filters["city_as_department"].lower().strip()
+ if "city_as_department" in filters
+ else ""
+ )
 
  if len(val) > 0:
  deps_uuids = val.split(",")
@@ -877,16 +973,12 @@ def get_queryset(self):
  uuid.UUID(deps_uuid)
  except ValueError:
  raise serializers.ValidationError(
- "'city_as_department' value must be a valid UUID"
+ "'organization' value must be a valid UUID"
  )
 
- deps = Department.objects.filter(uuid__in=deps_uuids).select_related(
- "municipality"
- )
- munis = [d.municipality for d in deps]
-
- queryset = queryset.filter(root_department__in=deps) | queryset.filter(
- municipality__in=munis
+ deps = Department.objects.filter(uuid__in=deps_uuids)
+ queryset = queryset.filter(department__in=deps) | queryset.filter(
+ root_department__in=deps
  )
 
  if "provider_type" in filters:
@@ -1127,6 +1219,7 @@ def list(self, request, *args, **kwargs):
 )
 
 
+@extend_schema_serializer(deprecate_fields=["service_point_id"])
 class AdministrativeDivisionSerializer(munigeo_api.AdministrativeDivisionSerializer):
  def to_representation(self, obj):
  ret = super(AdministrativeDivisionSerializer, self).to_representation(obj)
@@ -1171,6 +1264,19 @@ def to_representation(self, obj):
  return ret
 
 
+@extend_schema(
+ parameters=[
+ DIVISION_TYPE_PARAMETER,
+ LATITUDE_PARAMETER,
+ LONGITUDE_PARAMETER,
+ INPUT_PARAMETER,
+ OCD_ID_PARAMETER,
+ GEOMETRY_PARAMETER,
+ ORIGIN_ID_PARAMETER,
+ MUNICIPALITY_PARAMETER,
+ DATE_PARAMETER,
+ ]
+)
 class AdministrativeDivisionViewSet(munigeo_api.AdministrativeDivisionViewSet):
  serializer_class = AdministrativeDivisionSerializer
 
@@ -1196,6 +1302,17 @@ def get_queryset(self):
 register_view(AdministrativeDivisionViewSet, "administrative_division")
 
 
+@extend_schema(
+ parameters=[
+ STREET_PARAMETER,
+ OCD_MUNICIPALITY_PARAMETER,
+ BUILDING_NUMBER_PARAMETER,
+ LATITUDE_PARAMETER,
+ LONGITUDE_PARAMETER,
+ DISTANCE_PARAMETER,
+ BBOX_PARAMETER,
+ ],
+)
 class AddressViewSet(munigeo_api.AddressViewSet):
  serializer_class = munigeo_api.AddressSerializer
 
@@ -1210,7 +1327,7 @@ class PostalCodeAreaViewSet(munigeo_api.PostalCodeAreaViewSet):
 register_view(PostalCodeAreaViewSet, "postalcodearea")
 
 
-class AnnouncementSerializer(TranslatedModelSerializer, JSONAPISerializer):
+class AnnouncementSerializer(ServicesTranslatedModelSerializer, JSONAPISerializer):
  class Meta:
  model = Announcement
  exclude = ["id", "active"]
@@ -1224,7 +1341,7 @@ class AnnouncementViewSet(viewsets.ReadOnlyModelViewSet):
 register_view(AnnouncementViewSet, "announcement")
 
 
-class ErrorMessageSerializer(TranslatedModelSerializer, JSONAPISerializer):
+class ErrorMessageSerializer(ServicesTranslatedModelSerializer, JSONAPISerializer):
  class Meta:
  model = ErrorMessage
  exclude = ["id", "active"]

services/migrations/0103_unit_geometry_3d.py

@@ -0,0 +1,21 @@
+# Generated by Django 4.1.13 on 2024-07-04 06:06
+
+import django.contrib.gis.db.models.fields
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+ dependencies = [
+ ("services", "0102_unit_new_contract_type_fields"),
+ ]
+
+ operations = [
+ migrations.AddField(
+ model_name="unit",
+ name="geometry_3d",
+ field=django.contrib.gis.db.models.fields.GeometryField(
+ dim=3, null=True, srid=3067
+ ),
+ ),
+ ]

services/models/unit.py

@@ -101,6 +101,8 @@ class Unit(SoftDeleteModel):
 
  location = models.PointField(null=True, srid=PROJECTION_SRID) # lat, lng?
  geometry = models.GeometryField(srid=PROJECTION_SRID, null=True)
+ geometry_3d = models.GeometryField(srid=PROJECTION_SRID, null=True, dim=3)
+
  department = models.ForeignKey(Department, null=True, on_delete=models.CASCADE)
  root_department = models.ForeignKey(
  Department, null=True, related_name="descendant_units", on_delete=models.CASCADE