Add missing API documentation

services/api.py

@@ -15,7 +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
+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
@@ -44,6 +48,7 @@
 )
 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,
@@ -55,16 +60,20 @@
     ID_PARAMETER,
     INPUT_PARAMETER,
     LATITUDE_PARAMETER,
+    LEVEL_INTEGER_PARAMETER,
     LEVEL_PARAMETER,
     LONGITUDE_PARAMETER,
     MUNICIPALITY_PARAMETER,
     OCD_ID_PARAMETER,
     OCD_MUNICIPALITY_PARAMETER,
     ORGANIZATION_PARAMETER,
+    ORGANIZATION_TYPE_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, strtobool
 from services.utils.geocode_address import geocode_address
@@ -541,6 +550,7 @@ class JSONAPIViewSet(JSONAPIViewSetMixin, viewsets.ReadOnlyModelViewSet):
     pass
 
 
+@extend_schema(parameters=[ORGANIZATION_TYPE_PARAMETER, LEVEL_INTEGER_PARAMETER])
 class DepartmentViewSet(JSONAPIViewSet):
     queryset = Department.objects.all()
     serializer_class = DepartmentSerializer
@@ -685,6 +695,7 @@ def get_queryset(self):
 register_view(ServiceNodeViewSet, "service_node")
 
 
+@extend_schema(parameters=[ID_PARAMETER, ANCESTOR_ID_PARAMETER])
 class MobilityViewSet(ServiceNodeViewSet):
     queryset = MobilityServiceNode.objects.all()
     serializer_class = MobilitySerializer
@@ -970,13 +981,16 @@ def render(self, data, media_type=None, renderer_context=None):
 
 @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(
@@ -1361,6 +1375,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)

services/open_api_parameters.py

@@ -1,5 +1,13 @@
 from drf_spectacular.utils import OpenApiParameter
 
+ACCESSIBILITY_DESCRIPTION_PARAMETER = OpenApiParameter(
+    name="accessibility_description",
+    location=OpenApiParameter.QUERY,
+    description="If given displays the accessibility description of unit.",
+    required=False,
+    type=bool,
+)
+
 ANCESTOR_ID_PARAMETER = OpenApiParameter(
     name="ancestor",
     location=OpenApiParameter.QUERY,
@@ -92,6 +100,14 @@
     type=float,
 )
 
+LEVEL_INTEGER_PARAMETER = OpenApiParameter(
+    name="level",
+    location=OpenApiParameter.QUERY,
+    description="Filter by level.",
+    required=False,
+    type=int,
+)
+
 LEVEL_PARAMETER = OpenApiParameter(
     name="level",
     location=OpenApiParameter.QUERY,
@@ -141,6 +157,14 @@
     type=str,
 )
 
+ORGANIZATION_TYPE_PARAMETER = OpenApiParameter(
+    name="organization_type",
+    location=OpenApiParameter.QUERY,
+    description="Filter by organization type.",
+    required=False,
+    type=str,
+)
+
 ORIGIN_ID_PARAMETER = OpenApiParameter(
     name="origin_id",
     location=OpenApiParameter.QUERY,
@@ -172,3 +196,19 @@
     required=False,
     type=str,
 )
+
+UNIT_GEOMETRY_3D_PARAMETER = OpenApiParameter(
+    name="geometry_3d",
+    location=OpenApiParameter.QUERY,
+    description="If given displays the 3D geometry of unit if it exists.",
+    required=False,
+    type=bool,
+)
+
+UNIT_GEOMETRY_PARAMETER = OpenApiParameter(
+    name="geometry",
+    location=OpenApiParameter.QUERY,
+    description="If given displays the geometry of unit if it exists.",
+    required=False,
+    type=bool,
+)