create custom API documentation for gene_length endpoint

backend/metagenedb/api/catalog/views/gene.py

 import pandas as pd
-import django_filters.rest_framework
 from drf_yasg import openapi
 from drf_yasg.utils import swagger_auto_schema
-from rest_framework.viewsets import GenericViewSet, ModelViewSet
-from rest_framework import mixins
 from rest_framework import status
 from rest_framework.decorators import action
+from rest_framework.permissions import IsAdminUser
 from rest_framework.response import Response
+from rest_framework.viewsets import ModelViewSet
 
 from metagenedb.common.utils.df_operations import get_mask
 from metagenedb.apps.catalog.models import Gene
 from metagenedb.apps.catalog.serializers import GeneSerializer
 
 
-# Define global variable for API documentation
-window_size_param = openapi.Parameter('window_size', in_=openapi.IN_QUERY, description='Size of the window.',
-                                      type=openapi.TYPE_INTEGER, default=10000)
-# gene_length_schema = openapi.Schema("pouet", {}, type={'hihi': 'haha'})
-# gene_length_response = openapi.Response('Get the distribution of gene length for a given window size', schema=gene_length_schema)
+class DocGeneLength(object):
+    """
+    Define response for API documentation of gene length distribution method
+    {
+    "results": {
+        "counts": [
+            0,
+            887,
+        ],
+        "labels": [
+            "0-9999",
+            "10000-19999",
+            "20000-29999",
+        ]
+    }
+}
+    """
+    window_size_param = openapi.Parameter('window_size', in_=openapi.IN_QUERY, description='Size of the window.',
+                                          type=openapi.TYPE_INTEGER, default=10000)
+    counts = openapi.Schema(type="array", items=openapi.Schema(type="int"),
+                            description="Counts for every window_size")
+    labels = openapi.Schema(type="array", items=openapi.Schema(type="char"),
+                            description="Corresponding windows")
+    results = openapi.Schema(type="object", properties={'counts': counts, 'labels': labels},
+                             description="results of your request")
+    gene_length_schema = openapi.Schema(type="object", properties={'results': results})
+    gene_length_response = openapi.Response('Get the distribution of gene length for a given window size',
+                                            schema=gene_length_schema)
 
 
 class GeneViewSet(ModelViewSet):
@@ -25,6 +47,11 @@ class GeneViewSet(ModelViewSet):
     serializer_class = GeneSerializer
     GENE_LENGTH_COL = 'length'
 
+    def get_permissions(self):
+        if self.action == 'create':
+            self.permission_classes = [IsAdminUser, ]
+        return super(self.__class__, self).get_permissions()
+
     def _count_windows(self, df, window_size=10000, window_col=GENE_LENGTH_COL):
         """
         Count how many line of the df belong to each windows defined by the window_size for the window_col
@@ -45,12 +72,12 @@ class GeneViewSet(ModelViewSet):
         }
 
     @swagger_auto_schema(
-        manual_parameters=[window_size_param],
+        manual_parameters=[DocGeneLength.window_size_param],
         responses={
-        #     '200': gene_length_response,
-            '204': 'no content'
+            '200': DocGeneLength.gene_length_response,
+            '204': 'No genes on the catalog to build the distribution'
         },
-        operation_id='List of categories',
+        operation_id='Gene length distribution',
     )
     @action(methods=['get'], detail=False)
     def gene_length(self, request, window_size=10000):