added documentation for /api/back/establishments/<id>/employees/

apps/collection/views/back.py

@@ -118,7 +118,7 @@ class GuideListCreateView(GuideBaseView, generics.ListCreateAPIView):
 
     ### Response
     Return paginated list of guides.
-    I.e.:
+    E.g.:
     ```
     {
       "count": 58,

apps/establishment/serializers/back.py

@@ -15,7 +15,7 @@ from establishment import models, serializers as model_serializers
 from establishment.models import ContactEmail, ContactPhone, EstablishmentEmployee
 from establishment.serializers.common import ContactPhonesSerializer
 from gallery.models import Image
-from location.serializers import AddressDetailSerializer, TranslatedField, AddressBaseSerializer
+from location.serializers import AddressDetailSerializer, TranslatedField
 from main import models as main_models
 from main.models import Currency
 from main.serializers import AwardSerializer
@@ -529,10 +529,8 @@ class EstEmployeeBackSerializer(EmployeeBackSerializers):
             'toque_number',
             'available_for_events',
             'photo',
+            'photo_id',
         ]
-        extra_kwargs = {
-            'phone': {'write_only': True}
-        }
 
 
 class EstablishmentBackOfficeGallerySerializer(serializers.ModelSerializer):

apps/establishment/views/back.py

@@ -531,17 +531,18 @@ class EmployeeListCreateView(generics.ListCreateAPIView):
 
     #### Request
     Required fields:
-    * available_for_events (bool) - flag that responds for availability for events
+    * name (`str`) - employee name
 
     Non-required fields:
-    * name (`str`) - name
-    * last_name (`str`) - last name
+    * name (`str`) - employee name
+    * last_name (`str`) - employee last name
     * user (`int`) - user identifier
     * sex (`int`) - enum: `0 (Male), 1 (Female)`
     * birth_date (`str`) - birth datetime (datetime in a format `ISO-8601`)
     * email (`str`) - email address
     * phone (`str`) - phone number in a format `E164`
     * photo_id (`int`) - photo identifier
+    * available_for_events (bool) - flag that responds for availability for events
     """
     filter_class = filters.EmployeeBackFilter
     serializer_class = serializers.EmployeeBackSerializers
@@ -590,7 +591,47 @@ class EmployeesListSearchViews(generics.ListAPIView):
 
 
 class EstablishmentEmployeeListView(generics.ListCreateAPIView):
-    """Establishment employees list view."""
+    """
+    ## Establishment employees List/Create view.
+    ### *GET*
+    #### Description
+    Returning non-paginated list of employees by establishment identifier.
+    ##### Response
+    E.g.:
+    ```
+    [
+        {
+            "id": 1,
+            ...
+        }
+    ]
+    ```
+
+    ### *POST*
+    #### Description
+    Create a new instance of employee for establishment by establishment identifier.
+    #### Request
+    Required:
+    * name (`str`) - employee name
+
+    Additional:
+    * last_name (`str`) - employee last name
+    * user (`int`) - user identifier
+    * sex (`int`) - enum: `0 (Male), 1 (Female)`
+    * birth_date (`str`) - birth datetime (datetime in a format `ISO-8601`)
+    * email (`str`) - email address
+    * phone (`str`) - phone number in a format `E164`
+    * available_for_events (bool) - flag that responds for availability for events
+    * photo_id (`int`) - photo identifier
+
+    #### Response
+    ```
+    {
+        "id": 1,
+        ...
+    }
+    ```
+    """
     serializer_class = serializers.EstEmployeeBackSerializer
     pagination_class = None
     permission_classes = get_permission_classes(
@@ -613,7 +654,8 @@ class EmployeeRUDView(generics.RetrieveUpdateDestroyAPIView):
     """
     ## Employee Retrieve/Update/Destroy view
     ### *GET*
-    #### Retrieve a serialized object of employee.
+    #### Description
+    Retrieve a serialized object of employee.
     ##### Response
     ```
     {
@@ -638,7 +680,7 @@ class EmployeeRUDView(generics.RetrieveUpdateDestroyAPIView):
     * photo_id (`int`) - image identifier
     ##### Response
     Return an employee serialized object
-    I.e.:
+    E.g.:
     ```
     {
         "id": 1,
@@ -651,7 +693,7 @@ class EmployeeRUDView(generics.RetrieveUpdateDestroyAPIView):
     Delete an instance of employee
     ##### Response
     ```
-    No response data
+    No content
     ```
     """
     serializer_class = serializers.EmployeeBackSerializers
@@ -663,6 +705,16 @@ class EmployeeRUDView(generics.RetrieveUpdateDestroyAPIView):
 
 
 class RemoveAwardView(generics.DestroyAPIView):
+    """
+    ## Remove award view.
+    ### *DELETE*
+    #### Description
+    Remove an award from an employee by an employee identifier and an award identifier.
+    ##### Response
+    ```
+    No content
+    ```
+    """
     lookup_field = 'pk'
     serializer_class = serializers.EmployeeBackSerializers
     queryset = models.Employee.objects.with_back_office_related()
@@ -923,7 +975,25 @@ class EstablishmentPositionListView(generics.ListAPIView):
 
 
 class EstablishmentAdminView(generics.ListAPIView):
-    """Establishment admin list view."""
+    """
+    ## List establishment admins
+    ### *GET*
+    #### Description
+    Returning paginated list of establishment administrators by establishment slug.
+    ##### Response
+    ```
+    {
+      "count": 58,
+      "next": 2,
+      "previous": null,
+      "results": [
+        {
+            "id": 1,
+            ...
+        }
+      ]
+    }
+```    """
     serializer_class = serializers.EstablishmentAdminListSerializer
     permission_classes = get_permission_classes(
         IsEstablishmentManager,

apps/report/views/back.py

@@ -13,7 +13,7 @@ class ReportListCreateView(ReportBaseView, ListCreateAPIView):
     * category: integer (0 - Bug, 1 - Suggestion improvement)
     * url: char (URL)
     * description: text (problem description)
-    I.e.:
+    E.g.:
     ```
     {
         "category": 1,

apps/report/views/common.py

@@ -38,7 +38,7 @@ class ReportRetrieveView(ReportBaseView, generics.RetrieveAPIView):
     ## View for retrieving serialized instance.
     ### Response
     Return serialized object.
-    I.e.:
+    E.g.:
     ```
     {
         "count": 7,

apps/report/views/web.py

@@ -13,7 +13,7 @@ class ReportListCreateView(ReportBaseView, ListCreateAPIView):
     * category: integer (0 - Bug, 1 - Suggestion improvement)
     * url: char (URL)
     * description: text (problem description)
-    I.e.:
+    E.g.:
     ```
     {
         "category": 1,