Merge branch 'feature/services-api-documentation' into feature/unit-a…

…dd-geometry3d

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,29 @@
     UnitServiceDetails,
 )
 from services.models.unit import ORGANIZER_TYPES, PROVIDER_TYPES
+from services.open_api_parameters import (
+    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,
+)
 from services.utils import check_valid_concrete_field
 from services.utils.geocode_address import geocode_address
 
@@ -68,6 +96,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 +225,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 +296,7 @@ def to_representation(self, obj):
 
 
 class DepartmentSerializer(
-    TranslatedModelSerializer, MPTTModelSerializer, JSONAPISerializer
+    ServicesTranslatedModelSerializer, MPTTModelSerializer, JSONAPISerializer
 ):
     id = serializers.SerializerMethodField("get_uuid")
     parent = serializers.SerializerMethodField()
@@ -272,7 +318,7 @@ def get_parent(self, obj):
 
 
 class ServiceNodeSerializer(
-    TranslatedModelSerializer, MPTTModelSerializer, JSONAPISerializer
+    ServicesTranslatedModelSerializer, MPTTModelSerializer, JSONAPISerializer
 ):
     children = serializers.PrimaryKeyRelatedField(many=True, read_only=True)
 
@@ -326,7 +372,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 +414,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 +518,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 +539,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 +552,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 +586,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 +614,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 +643,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)
@@ -812,6 +868,17 @@ def render(self, data, media_type=None, renderer_context=None):
         return render_to_string("kml.xml", resp)
 
 
+@extend_schema(
+    parameters=[
+        ID_PARAMETER,
+        OCD_MUNICIPALITY_PARAMETER,
+        ORGANIZATION_PARAMETER,
+        CITY_AS_DEPARTMENT_PARAMETER,
+        PROVIDER_TYPE_PARAMETER,
+        PROVIDER_TYPE_NOT_PARAMETER,
+        LEVEL_PARAMETER,
+    ]
+)
 class UnitViewSet(
     munigeo_api.GeoModelAPIView, JSONAPIViewSet, viewsets.ReadOnlyModelViewSet
 ):
@@ -846,6 +913,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:
@@ -1127,6 +1200,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 +1245,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 +1283,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 +1308,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 +1322,7 @@ class AnnouncementViewSet(viewsets.ReadOnlyModelViewSet):
 register_view(AnnouncementViewSet, "announcement")
 
 
-class ErrorMessageSerializer(TranslatedModelSerializer, JSONAPISerializer):
+class ErrorMessageSerializer(ServicesTranslatedModelSerializer, JSONAPISerializer):
     class Meta:
         model = ErrorMessage
         exclude = ["id", "active"]