done "GM-367"

apps/location/serializers/common.py

@@ -69,6 +69,11 @@ class RegionSerializer(serializers.ModelSerializer):
         queryset=models.Country.objects.all(),
         write_only=True
     )
+    parent_region_id = serializers.PrimaryKeyRelatedField(
+        source='parent_region',
+        queryset=models.Region.objects.all(),
+        write_only=True
+    )
     parent_region = ParentRegionSerializer(read_only=True)
 
     class Meta:
@@ -78,6 +83,7 @@ class RegionSerializer(serializers.ModelSerializer):
             'name',
             'code',
             'parent_region',
+            'parent_region_id',
             'country',
             'country_id'
         ]

apps/location/views/back.py

@@ -125,9 +125,51 @@ class AddressRUDView(common.AddressViewMixin, generics.RetrieveUpdateDestroyAPIV
 
 # City
 class CityListCreateView(common.CityViewMixin, generics.ListCreateAPIView):
-    """Create view for model City."""
+    """
+    ## List/Create view
+    ### *GET*
+    #### Description
+    Return paginated list of cities ordered by a locale and filtered by a country code.
+    Available filters:
+    * search (`str`) - search city by name
+    * country_code (`str`) - search city by its country code
+    ##### Response
+    E.g.:
+    ```
+    {
+      "count": 58,
+      "next": 2,
+      "previous": null,
+      "results": [
+        {
+            "id": 1,
+            ...
+        }
+      ]
+    }
+    ```
+    ### *POST*
+    #### Description
+    Create a new city object.
+    ##### Request
+    Required
+    * region_id (`int`) - region identifier
+    * country_id (`int`) - country identifier
+    Non-required:
+     * image_id (`int`) - image identifier
+     * name (`str`) - city name
+     * postal_code (`str`) - city postal code
+     * is_island (`boolean`) - flag that responds for is an island is this city
+    ##### Response
+    E.g.:
+    ```
+    {
+        "id": 1,
+        ...
+    }
+    ```
+    """
     serializer_class = serializers.CityBaseSerializer
-    queryset = models.City.objects.all()
     filter_class = filters.CityBackFilter
     permission_classes = get_permission_classes(
         IsEstablishmentManager,
@@ -144,23 +186,109 @@ class CityListCreateView(common.CityViewMixin, generics.ListCreateAPIView):
         return qs
 
 
-class CityListSearchView(common.CityViewMixin, generics.ListCreateAPIView):
+class CityListSearchView(CityListCreateView):
-    """Create view for model City."""
+    """
-    serializer_class = serializers.CityBaseSerializer
+    ## List/Create view
-    queryset = models.City.objects.all()\
+    ### *GET*
-        .annotate(locale_name=KeyTextTransform(get_current_locale(), 'name'))\
+    #### Description
-        .order_by('locale_name')
+    Return list of cities **without pagination**, ordered by a locale and filtered by a country code.
-    filter_class = filters.CityBackFilter
+    Available filters:
+    * search (`str`) - search city by name
+    * country_code (`str`) - search city by its country code
+    ##### Response
+    E.g.:
+    ```
+    {
+      "count": 58,
+      "next": 2,
+      "previous": null,
+      "results": [
+        {
+            "id": 1,
+            ...
+        }
+      ]
+    }
+    ```
+    ### *POST*
+    #### Description
+    Create a new city object.
+    ##### Request
+    Required
+    * region_id (`int`) - region identifier
+    * country_id (`int`) - country identifier
+    Non-required:
+     * image_id (`int`) - image identifier
+     * name (`str`) - city name
+     * postal_code (`str`) - city postal code
+     * is_island (`boolean`) - flag that responds for is an island is this city
+    ##### Response
+    E.g.:
+    ```
+    {
+        "id": 1,
+        ...
+    }
+    ```
+    """
     pagination_class = None
-    permission_classes = get_permission_classes(
+
-        IsEstablishmentManager,
+    def get_queryset(self):
-        IsEstablishmentAdministrator,
+        """An overridden get_queryset method."""
-        IsGuest,
+        return (
-    )
+            models.City.objects.
+                annotate(locale_name=KeyTextTransform(get_current_locale(), 'name')).
+                order_by('locale_name')
+        )
 
 
 class CityRUDView(common.CityViewMixin, generics.RetrieveUpdateDestroyAPIView):
-    """RUD view for model City."""
+    """
+    ## Retrieve/Update/Destroy view
+    ### *GET*
+    #### Description
+    Retrieve serialized instance of city object by an identifier
+    ##### Response
+    E.g.:
+    ```
+    {
+        "id": 1,
+        ...
+    }
+    ```
+
+    ### *PUT*/*PATCH*
+    #### Description
+    Completely/Partially update a city object by an identifier.
+    ##### Request
+    Available:
+    * region_id (`int`) - region identifier
+    * country_id (`int`) - country identifier
+    * image_id (`int`) - image identifier
+    * name (`str`) - city name
+    * postal_code (`str`) - city postal code
+    * is_island (`boolean`) - flag that responds for is an island is this city
+    ##### Response
+    E.g.:
+    ```
+    {
+        "id": 1,
+        ...
+    }
+    ```
+
+    ### *DELETE*
+    #### Description
+    Delete an instance of city by identifier
+    ##### Response
+    E.g.:
+    ```
+    {
+        "id": 1,
+        ...
+    }
+    ```
+    """
     serializer_class = serializers.CityDetailSerializer
     permission_classes = get_permission_classes(
         IsEstablishmentManager,
@@ -178,7 +306,44 @@ class CityRUDView(common.CityViewMixin, generics.RetrieveUpdateDestroyAPIView):
 
 # Region
 class RegionListCreateView(common.RegionViewMixin, generics.ListCreateAPIView):
-    """Create view for model Region"""
+    """
+    ## List/Create view
+    ### *GET*
+    #### Description
+    Return non-paginated list of regions.
+    Available filters:
+    * country_id (`int`) - filter by a country identifier
+    * sub_regions_by_region_id (`int`) - filter sub regions by region identifier
+    * without_parent_region (`boolean`) - flag that responds for returning regions
+    with/without parent region
+    ##### Responds
+    E.g.:
+    ```
+    [
+        {
+            "id": 1,
+            ...
+        }
+    ]
+    ```
+    ### *POST*
+    #### Description
+    Create new region/sub region
+    ##### Request
+    Available:
+    * name (`str`) - (sub)region name
+    * code (`str`) - (sub)region code
+    * country_id (`int`) - identifier of `country`
+    * parent_region_id (`int`) - identifier of `parent region`
+    ##### Response
+    E.g.:
+    ```
+    {
+        "id": 1,
+        ...
+    }
+    ```
+    """
     pagination_class = None
     serializer_class = serializers.RegionSerializer
     # ordering_fields = 'name'
@@ -191,7 +356,47 @@ class RegionListCreateView(common.RegionViewMixin, generics.ListCreateAPIView):
 
 
 class RegionRUDView(common.RegionViewMixin, generics.RetrieveUpdateDestroyAPIView):
-    """Retrieve view for model Region"""
+    """
+    ## Retrieve/Update/Destroy view
+    ### *GET*
+    #### Description
+    Return serialized object of (sub)region by an identifier.
+    ##### Responds
+    E.g.:
+    ```
+    [
+        {
+            "id": 1,
+            ...
+        }
+    ]
+    ```
+    ### *PATCH*/*PUT*
+    #### Description
+    Completely/Partially update a (sub)region object by an identifier.
+    ##### Request
+    Available:
+    * name (`str`) - (sub)region name
+    * code (`str`) - (sub)region code
+    * country_id (`int`) - identifier of `country`
+    * parent_region_id (`int`) - identifier of `parent region`
+    ##### Response
+    E.g.:
+    ```
+    {
+        "id": 1,
+        ...
+    }
+    ```
+    ### *DELETE*
+    #### Description
+    Delete an instance of (sub)region
+    ##### Response
+    E.g.:
+    ```
+    No content
+    ```
+    """
     serializer_class = serializers.RegionSerializer
     permission_classes = get_permission_classes(
         IsEstablishmentManager,
@@ -212,7 +417,37 @@ class CountryBaseViewMixin:
 
 
 class CountryListCreateView(CountryBaseViewMixin, generics.ListCreateAPIView):
-    """List/Create view for model Country."""
+    """
+    ## List/Create view.
+    ### *GET*
+    #### Description
+    Return non-paginated list of countries ordered by a locale.
+    ##### Response
+    E.g.:
+    ```
+    [
+        {
+            "id": 1,
+            ...
+        }
+    ]
+    ```
+    ### *POST*
+    #### Description
+    Create new city
+    ##### Request
+    * code (`str`) - country code
+    * svg_image (`file`) - svg icon of country flag
+    * name (`JSON`) - country name, like - `{"en-GB": "text", "ru-RU": Text}`
+    ##### Response
+    E.g.:
+    ```
+    {
+        "id": 1,
+        ...
+    }
+    ```
+    """
     queryset = (models.Country.objects.annotate(
         locale_name=KeyTextTransform(get_current_locale(), 'name')).order_by('locale_name'))
     serializer_class = serializers.CountryBackSerializer
@@ -220,7 +455,46 @@ class CountryListCreateView(CountryBaseViewMixin, generics.ListCreateAPIView):
 
 
 class CountryRUDView(CountryBaseViewMixin, generics.RetrieveUpdateDestroyAPIView):
-    """RUD view for model Country."""
+    """
+    ## Retrieve/Update/Destroy view.
+    ### *GET*
+    #### Description
+    Retrieve serialized object of country by identifier
+    ##### Response
+    E.g.:
+    ```
+    {
+        "id": 1,
+        ...
+    }
+    ```
+
+    ### *PUT*/*PATCH*
+    #### Description
+    Completely/Partially update an address object by an identifier.
+    ##### Request
+    Available:
+    * code (`str`) - country code
+    * svg_image (`file`) - svg icon of country flag
+    * name (`str`) - country name
+    ##### Response
+    E.g.:
+    ```
+    {
+        "id": 1,
+        ...
+    }
+    ```
+
+    ### *DELETE*
+    #### Description
+    Delete a country object by an identifier.
+    ##### Response
+    E.g.:
+    ```
+    No content
+    ```
+    """
     serializer_class = serializers.CountryBackSerializer