Merge pull request #265 from Mosquito-Alert/fix_openapi_schema

Fix openapi schema + prepare for openapi generator

Author: epou

api/auth/schema.py

@@ -1,5 +1,20 @@
-from drf_spectacular.contrib.rest_framework_simplejwt import SimpleJWTScheme
+from rest_framework import serializers
+
+from drf_spectacular.contrib.rest_framework_simplejwt import SimpleJWTScheme, TokenObtainPairSerializerExtension
+from drf_spectacular.utils import inline_serializer
 
 
 class AppUserJWTAuthentication(SimpleJWTScheme):
     target_class = "api.auth.authentication.AppUserJWTAuthentication"
+
+class AppUserTokenObtainPairSerializer(TokenObtainPairSerializerExtension):
+    target_class = "api.auth.serializers.AppUserTokenObtainPairSerializer"
+
+    def map_serializer(self, auto_schema, direction):
+        Fixed = inline_serializer('Fixed', fields={
+            'uuid': serializers.UUIDField(write_only=True),
+            'password': serializers.CharField(write_only=True),
+            'access': serializers.CharField(read_only=True),
+            'refresh': serializers.CharField(read_only=True),
+        })
+        return auto_schema._map_serializer(Fixed, direction)

api/auth/serializers.py

@@ -9,7 +9,7 @@
 
 
 class AppUserTokenObtainSerializer(TokenObtainSerializer):
-    uuid = serializers.UUIDField(required=True)
+    uuid = serializers.UUIDField(write_only=True, required=True)
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)

api/base_serializers.py

@@ -29,29 +29,36 @@ def __new__(cls, *args, **kwargs):
             raise ImproperlyConfigured(
                 "`{cls}.model` must be a django Model".format(cls=cls.__name__)
             )
-        return super().__new__(cls, *args, **kwargs)
 
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        field_value_serializer_mapping = self.field_value_serializer_mapping
-        self.field_value_serializer_mapping = {}
+        instance = super().__new__(cls, *args, **kwargs)
+
+        field_value_serializer_mapping = cls.field_value_serializer_mapping
+        instance.field_value_serializer_mapping = {}
         for field_value, serializer in field_value_serializer_mapping.items():
-            if callable(serializer):
+            if isinstance(serializer, serializers.Serializer):
+                serializer = serializer
+            else:
                 serializer = serializer(*args, **kwargs)
-                serializer.parent = self
+                serializer.parent = instance
+
+            instance.field_value_serializer_mapping[field_value] = serializer
 
-            self.field_value_serializer_mapping[field_value] = serializer
+        return instance
 
     def to_representation(self, instance):
         serializer = self._get_serializer_for_instance(instance=instance)
-        return serializer.to_representation(instance)
+        ret = serializer.to_representation(instance)
+        ret[self.resource_type_field_name] = getattr(instance, self.resource_type_field_name)
+        return ret
 
     def to_internal_value(self, data):
         if self.instance:
             serializer = self._get_serializer_for_instance(instance=self.instance)
         else:
             serializer = self._get_serializer_for_data(data=data)
-        return serializer.to_internal_value(data=data)
+        ret = serializer.to_internal_value(data=data)
+        ret[self.resource_type_field_name] = data[self.resource_type_field_name]
+        return ret
 
     def create(self, validated_data):
         serializer = self._get_serializer_for_data(data=validated_data)
@@ -82,7 +89,9 @@ def run_validation(self, data=empty):
             serializer = self._get_serializer_for_instance(instance=self.instance)
         else:
             serializer = self._get_serializer_for_data(data=data)
-        return serializer.run_validation(data)
+        validated_data = serializer.run_validation(data)
+        validated_data[self.resource_type_field_name] = data[self.resource_type_field_name]
+        return validated_data
 
     def _get_serializer_for_type(self, type_value):
         try:

api/schema.py

@@ -1,10 +1,10 @@
+from drf_spectacular.contrib.rest_polymorphic import PolymorphicSerializerExtension
+from drf_spectacular.drainage import warn
 from drf_spectacular.extensions import (
     OpenApiSerializerFieldExtension,
-    OpenApiSerializerExtension,
 )
 from drf_spectacular.plumbing import build_object_type, build_basic_type
 from drf_spectacular.types import OpenApiTypes
-from drf_spectacular.plumbing import force_instance
 
 
 class PointFieldExtension(OpenApiSerializerFieldExtension):
@@ -20,31 +20,57 @@ def map_serializer_field(self, auto_schema, direction):
             required=["latitude", "longitude"] if self.target.required else None
         )
 
-class FieldPolymorphicSerializerExtension(OpenApiSerializerExtension):
+class FieldPolymorphicSerializerExtension(PolymorphicSerializerExtension):
     target_class = "api.base_serializers.FieldPolymorphicSerializer"
 
-    def get_name(self):
-        return self.target.model._meta.model_name
-
+    # NOTE: even if the implementation in PolymorphicSerializerExtension works pretty well,
+    # it causes errors on openapi-generator.
+    # That is because it's creating a Typed component (see self.build_typed_component())
+    # And it's a bug in the generator: https://github.com/OpenAPITools/openapi-generator/issues/19261
+    # See: https://redocly.com/docs/resources/discriminator
     def map_serializer(self, auto_schema, direction):
         sub_components = []
+        serializer = self.target
+
         for (
-            resource_type_field_name,
+            resource_type_field_name_value,
             sub_serializer,
         ) in self.target.field_value_serializer_mapping.items():
-            sub_serializer = force_instance(sub_serializer)
-            resolved = auto_schema.resolve_serializer(sub_serializer, direction)
-            sub_components.append((resource_type_field_name, resolved.ref))
+            sub_serializer.partial = serializer.partial
+            component = auto_schema.resolve_serializer(sub_serializer, direction)
+
+            # Define the discriminator field schema
+            field_schema = build_basic_type(OpenApiTypes.STR)
+            field_schema['enum'] = [resource_type_field_name_value,] # NOTE: in openapi 3.1 is 'const'
+            # field_schema['default'] = resource_type_field_name_value
+
+            component.schema['properties'] = {
+                serializer.resource_type_field_name: field_schema,
+                **component.schema['properties']
+            }
+            component.schema['required'].append(serializer.resource_type_field_name)
+
+            sub_components.append((resource_type_field_name_value, component.ref))
+
+            if not resource_type_field_name_value:
+                warn(
+                    f'discriminator mapping key is empty for {sub_serializer.__class__}. '
+                    f'this might lead to code generation issues.'
+                )
+
+        one_of_list = []
+        for _, ref in sub_components:
+            if ref not in one_of_list:
+                one_of_list.append(ref)
 
         return {
-            "oneOf": [schema for _, schema in sub_components],
+            "oneOf": one_of_list,
             "discriminator": {
-                "propertyName": self.target.resource_type_field_name,
+                "propertyName": serializer.resource_type_field_name,
                 "mapping": {
-                    resource_type: schema["$ref"]
-                    for resource_type, schema in sub_components
-                },
-            },
+                    resource_type_field_name_value: ref["$ref"]
+                    for resource_type_field_name_value, ref in sub_components},
+            }
         }
 
 

api/serializers.py

@@ -6,9 +6,6 @@
 
 from rest_framework import serializers
 
-from drf_spectacular.utils import extend_schema_field
-from drf_spectacular.types import OpenApiTypes
-
 from drf_extra_fields.geo_fields import PointField
 
 from tigaserver_app.models import (
@@ -103,8 +100,7 @@ class DetailNotificationSerializer(serializers.ModelSerializer):
     title = serializers.SerializerMethodField(read_only=True)
     body = serializers.SerializerMethodField(read_only=True)
 
-    @extend_schema_field(OpenApiTypes.BOOL)
-    def get_seen(self, obj):
+    def get_seen(self, obj) -> bool:
         user = self.context.get("request").user
         if not isinstance(user, TigaUser):
             return False
@@ -116,17 +112,15 @@ def get_seen(self, obj):
             user=self.context.get("request").user
         ).exists() or (obj.user == user and obj.acknowledged)
 
-    @extend_schema_field(OpenApiTypes.STR)
-    def get_title(self, obj):
+    def get_title(self, obj) -> str:
         if obj.notification_content is None:
             return ""
 
         return obj.notification_content.get_title(
             language_code=self.context.get("request").LANGUAGE_CODE
         )
 
-    @extend_schema_field(OpenApiTypes.STR)
-    def get_body(self, obj):
+    def get_body(self, obj) -> str:
         if obj.notification_content is None:
             return ""
 
@@ -173,21 +167,29 @@ class BaseNotificationCreateSerializer(serializers.ModelSerializer):
     def RECEIVER_TYPE(self):
         raise NotImplementedError
 
-    receiver_type = WritableSerializerMethodField(
-        field_class=serializers.ChoiceField,
-        choices=["user", "topic"],
-        required=True
-    )
-
     title_en = serializers.CharField(write_only=True)
     body_en = serializers.CharField(write_only=True)
 
     created_at = serializers.DateTimeField(source="date_comment", read_only=True)
     expert = serializers.HiddenField(default=serializers.CurrentUserDefault())
 
-    @extend_schema_field(OpenApiTypes.STR)
-    def get_receiver_type(self, obj):
-        return self.RECEIVER_TYPE
+    def __init__(self, *args, **kwargs):
+        # Call the parent constructor first
+        super().__init__(*args, **kwargs)
+
+        # Add a dynamic field
+        self.fields['receiver_type'] = serializers.ChoiceField(
+            choices=[self.RECEIVER_TYPE,],
+            write_only=True,
+            required=True
+        )
+
+        # Re-order the fields with 'receiver_type' at the start
+        from collections import OrderedDict
+        self.fields = OrderedDict(
+            [('receiver_type', self.fields['receiver_type'])] +
+            [(key, field) for key, field in self.fields.items() if key != 'receiver_type']
+        )
 
     @transaction.atomic
     def create(self, validated_data):
@@ -203,7 +205,12 @@ def create(self, validated_data):
 
     class Meta:
         model = Notification
-        fields = ("id", "receiver_type", "created_at", "title_en", "body_en")
+        fields = (
+            "id",
+            "created_at",
+            "title_en",
+            "body_en"
+        )
 
 
 class UserNotificationCreateSerializer(BaseNotificationCreateSerializer):
@@ -235,11 +242,10 @@ def validate(self, data):
         return data
 
     class Meta(BaseNotificationCreateSerializer.Meta):
-        fields = (
-            "receiver_type",
+        fields = BaseNotificationCreateSerializer.Meta.fields + (
             "report_uuid",
             "user_uuid",
-        ) + BaseNotificationCreateSerializer.Meta.fields
+        )
 
 
 class TopicNotificationCreateSerializer(BaseNotificationCreateSerializer):
@@ -268,10 +274,7 @@ def create(self, validated_data):
         return instance
 
     class Meta(BaseNotificationCreateSerializer.Meta):
-        fields = (
-            "receiver_type",
-            "topic_code",
-        ) + BaseNotificationCreateSerializer.Meta.fields
+        fields = BaseNotificationCreateSerializer.Meta.fields + ("topic_code", )
 
 #### END NOTIFICATION SERIALIZERS ####
 
@@ -390,7 +393,6 @@ class Meta:
             "short_id",
             "user_uuid",
             "user",
-            "type",
             "session_id",
             "created_at",
             "sent_at",

api/tests/integration/notifications/create.tavern.yml

@@ -75,10 +75,7 @@ stages:
       method: "POST"
     response:
       status_code: 201
-      json: &response_validation
-        id: !anyint
-        receiver_type: "user"
-        created_at: !re_fullmatch \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}Z
+      json: !force_format_include "{response_data_validation}"
   - name: Create topic notification using auth user with permissions
     request:
       url: "{api_live_url}/{endpoint}/"
@@ -92,6 +89,4 @@ stages:
       method: "POST"
     response:
       status_code: 201
-      json:
-        <<: *response_validation
-        receiver_type: "topic"
+      json: !force_format_include "{response_data_validation}"

api/tests/integration/notifications/schema.yml

@@ -6,3 +6,11 @@ description: Login information for test server
 
 variables:
   endpoint: "notifications"
+  response_data_validation:
+    id: !anyint
+    report_uuid: !anything
+    expert_id: !anything
+    created_at: !re_fullmatch \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{6}Z
+    title: !anystr
+    body: !anystr
+    seen: !anybool

api/urls.py

@@ -5,7 +5,7 @@
 
 from drf_spectacular.settings import spectacular_settings
 from drf_spectacular.utils import extend_schema
-from drf_spectacular.views import SpectacularRedocView, SpectacularAPIView
+from drf_spectacular.views import SpectacularRedocView, SpectacularAPIView, SpectacularJSONAPIView
 
 from .views import (
     UserViewSet,
@@ -51,6 +51,7 @@ def get(self, request, *args, **kwargs):
 api_urlpatterns += router.urls
 
 urlpatterns = [
-    path("schema/", SpectacularAPIView.as_view(), name="schema"),
+    path("openapi.yml", SpectacularAPIView.as_view(), name="schema"),
+    path("openapi.json", SpectacularJSONAPIView.as_view(), name="schema-json"),
     re_path("$^", CustomRedocView.as_view(url_name="schema"), name="redoc"),
 ] + api_urlpatterns