From 4559b0eeeb72eb9e8e48541c7dcd7f3aae9d1562 Mon Sep 17 00:00:00 2001 From: Anatoly Date: Fri, 7 Feb 2020 17:28:30 +0300 Subject: [PATCH] added a documentation for gallery --- apps/establishment/views/back.py | 58 ++++++++++++++++++++++++++++++-- apps/gallery/views.py | 50 ++++++++++++++++++++++++++- apps/news/views.py | 56 ++++++++++++++++++++++++++++-- apps/product/views/back.py | 56 ++++++++++++++++++++++++++++-- 4 files changed, 212 insertions(+), 8 deletions(-) diff --git a/apps/establishment/views/back.py b/apps/establishment/views/back.py index 4f1afaa5..4331b502 100644 --- a/apps/establishment/views/back.py +++ b/apps/establishment/views/back.py @@ -1021,7 +1021,38 @@ class EstablishmentSubtypeRUDView(generics.RetrieveUpdateDestroyAPIView): class EstablishmentGalleryCreateDestroyView(EstablishmentMixinViews, CreateDestroyGalleryViewMixin): - """Resource for a create|destroy gallery for establishment for back-office users.""" + """ + ## Establishment gallery image Create/Destroy view + ### *POST* + #### Description + Attaching existing **image** by `image identifier` to **establishment** by `establishment slug` + in request kwargs. + ##### Request + ``` + No body + ``` + ##### Response + E.g.: + ``` + No content + ``` + + ### *DELETE* + #### Description + Delete existing **gallery image** from **establishment** gallery, by `image identifier` + and `establishment slug` in request kwargs. + + **Note**: + > Image wouldn't be deleted after all. + ##### Request + ``` + No body + ``` + ##### Response + ``` + No content + ``` + """ lookup_field = 'slug' serializer_class = serializers.EstablishmentBackOfficeGallerySerializer permission_classes = get_permission_classes() @@ -1044,7 +1075,28 @@ class EstablishmentGalleryCreateDestroyView(EstablishmentMixinViews, class EstablishmentGalleryListView(EstablishmentMixinViews, generics.ListAPIView): - """Resource for returning gallery for establishment for back-office users.""" + """ + ## Establishment gallery image list view + ### *GET* + #### Description + Returning paginated list of establishment images by `establishment slug`, + with cropped images. + ##### Response + E.g.: + ``` + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "id": 11, + ... + } + ] + } + ``` + """ lookup_field = 'slug' serializer_class = serializers.ImageBaseSerializer permission_classes = get_permission_classes() @@ -1054,7 +1106,7 @@ class EstablishmentGalleryListView(EstablishmentMixinViews, qs = super(EstablishmentGalleryListView, self).get_queryset() establishment = get_object_or_404(qs, slug=self.kwargs.get('slug')) - # May raise a permission denied + # May raises a permission denied self.check_object_permissions(self.request, establishment) return establishment diff --git a/apps/gallery/views.py b/apps/gallery/views.py index 80b89cea..45192530 100644 --- a/apps/gallery/views.py +++ b/apps/gallery/views.py @@ -9,6 +9,7 @@ from utils.permissions import IsContentPageManager, IsCountryAdmin, IsEstablishm IsProducerFoodInspector, IsEstablishmentAdministrator from . import tasks, models, serializers + class ImageBaseView(generics.GenericAPIView): """Base Image view.""" model = models.Image @@ -20,7 +21,54 @@ class ImageBaseView(generics.GenericAPIView): class ImageListCreateView(ImageBaseView, generics.ListCreateAPIView): - """List/Create Image view.""" + """ + ## List/Create view + ### *GET* + #### Description + Get paginated list of images, with ordering by field `modified` (descending) + #### Response + E.g.: + ``` + { + "count": 40595, + "next": 2, + "previous": null, + "results": [ + { + "id": 47336, + ... + } + ] + } + ``` + ### *POST* + #### Description + Upload an image on a server. + ##### Request + Required: + * file (`file`) - download file + Available: + * orientation (`enum`) - default: `null` + ``` + 0 (Horizontal) + 1 (Vertical) + ``` + * title (`str`) - title of image file (default - `''`) + * is_public (`bool`) - flag that responds for availability + for displaying (default - `True`) + * preview (`file`) - download preview file (default - `null`) + * link (`str`) - mp4 or youtube video link (default - `null`) + * order (`int`) - order number (default - `0`) + ##### Response + E.g.: + ``` + { + "id": 47336, + ... + } + + ``` + """ class MediaForEstablishmentView(ImageBaseView, generics.ListCreateAPIView): diff --git a/apps/news/views.py b/apps/news/views.py index b0c11e08..5071d79e 100644 --- a/apps/news/views.py +++ b/apps/news/views.py @@ -176,7 +176,38 @@ class NewsBackOfficeLCView(NewsBackOfficeMixinView, class NewsBackOfficeGalleryCreateDestroyView(NewsBackOfficeMixinView, CreateDestroyGalleryViewMixin): - """Resource for a create gallery for news for back-office users.""" + """ + ## News gallery image Create/Destroy view + ### *POST* + #### Description + Attaching existing **image** by `image identifier` to **news** by `news identifier` + in request kwargs. + ##### Request + ``` + No body + ``` + ##### Response + E.g.: + ``` + No content + ``` + + ### *DELETE* + #### Description + Delete existing **gallery image** from **news** gallery, by `image identifier` + and `news identifier` in request kwargs. + + **Note**: + > Image wouldn't be deleted after all. + ##### Request + ``` + No body + ``` + ##### Response + ``` + No content + ``` + """ serializer_class = serializers.NewsBackOfficeGallerySerializer def create(self, request, *args, **kwargs): @@ -203,7 +234,28 @@ class NewsBackOfficeGalleryCreateDestroyView(NewsBackOfficeMixinView, class NewsBackOfficeGalleryListView(NewsBackOfficeMixinView, generics.ListAPIView): - """Resource for returning gallery for news for back-office users.""" + """ + ## News gallery image list view + ### *GET* + #### Description + Returning paginated list of news images by `news identifier`, + with cropped images. + ##### Response + E.g.: + ``` + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "id": 11, + ... + } + ] + } + ``` + """ serializer_class = ImageBaseSerializer def get_object(self): diff --git a/apps/product/views/back.py b/apps/product/views/back.py index a660d242..a1c7fee0 100644 --- a/apps/product/views/back.py +++ b/apps/product/views/back.py @@ -46,7 +46,38 @@ class ProductSubTypeBackOfficeMixinView: class ProductBackOfficeGalleryCreateDestroyView(ProductBackOfficeMixinView, CreateDestroyGalleryViewMixin): - """Resource for a create gallery for product for back-office users.""" + """ + ## Product gallery image Create/Destroy view + ### *POST* + #### Description + Attaching existing **image** by `image identifier` to **product** by `product identifier` + in request kwargs. + ##### Request + ``` + No body + ``` + ##### Response + E.g.: + ``` + No content + ``` + + ### *DELETE* + #### Description + Delete existing **gallery image** from **product** gallery, by `image identifier` + and `product identifier` in request kwargs. + + **Note**: + > Image wouldn't be deleted after all. + ##### Request + ``` + No body + ``` + ##### Response + ``` + No content + ``` + """ serializer_class = serializers.ProductBackOfficeGallerySerializer def get_object(self): @@ -66,7 +97,28 @@ class ProductBackOfficeGalleryCreateDestroyView(ProductBackOfficeMixinView, class ProductBackOfficeGalleryListView(ProductBackOfficeMixinView, generics.ListAPIView): - """Resource for returning gallery for product for back-office users.""" + """ + ## Product gallery image list view + ### *GET* + #### Description + Returning paginated list of product images by `product identifier`, + with cropped images. + ##### Response + E.g.: + ``` + { + "count": 1, + "next": null, + "previous": null, + "results": [ + { + "id": 11, + ... + } + ] + } + ``` + """ serializer_class = ImageBaseSerializer def get_object(self):