diff --git a/apps/location/serializers/common.py b/apps/location/serializers/common.py index 9221c3b6..5e07b02d 100644 --- a/apps/location/serializers/common.py +++ b/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' ] diff --git a/apps/location/views/back.py b/apps/location/views/back.py index a7eab166..0bf90b8f 100644 --- a/apps/location/views/back.py +++ b/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): - """Create view for model City.""" - serializer_class = serializers.CityBaseSerializer - queryset = models.City.objects.all()\ - .annotate(locale_name=KeyTextTransform(get_current_locale(), 'name'))\ - .order_by('locale_name') - filter_class = filters.CityBackFilter +class CityListSearchView(CityListCreateView): + """ + ## List/Create view + ### *GET* + #### Description + Return list of cities **without pagination**, 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, + ... + } + ``` + """ pagination_class = None - permission_classes = get_permission_classes( - IsEstablishmentManager, - IsEstablishmentAdministrator, - IsGuest, - ) + + def get_queryset(self): + """An overridden get_queryset method.""" + 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