Improve the documentation of the document creation API endpoint.

GitHub issue #255. Thanks to @lcerliani opening the issue.

Signed-off-by: Roberto Rosario <roberto.rosario.gonzalez@gmail.com>

mayan/apps/documents/api_views.py

@@ -120,16 +120,18 @@ class APIDocumentDownloadView(DownloadMixin, generics.RetrieveAPIView):
 
 
 class APIDocumentListView(generics.ListCreateAPIView):
-    """
-    Returns a list of all the documents.
-    """
-
     filter_backends = (MayanObjectPermissionsFilter,)
     mayan_object_permissions = {'GET': (permission_document_view,)}
     mayan_view_permissions = {'POST': (permission_document_create,)}
     permission_classes = (MayanPermission,)
     queryset = Document.objects.all()
 
+    def get(self, *args, **kwargs):
+        """
+        Returns a list of all the documents.
+        """
+        return super(APIDocumentListView, self).get(*args, **kwargs)
+
     def get_serializer_class(self):
         if self.request.method == 'GET':
             return DocumentSerializer
@@ -142,8 +144,34 @@ class APIDocumentListView(generics.ListCreateAPIView):
     def post(self, *args, **kwargs):
         """
         Create a new document.
+        Endpoint returns a 202 status code to indicate that a document is not
+        immediately created at request. From the request data, the creation of
+        a document is instead queued as a background task. An ID that
+        represents the eventual document is returned.
+        ---
+        omit_serializer: false
+        parameters:
+            - name: description
+              paramType: form
+              type: file string
+            - name: document_type
+              paramType: form
+              required: true
+              type: file string
+            - name: file
+              paramType: form
+              required: true
+              type: file object
+            - name: label
+              paramType: form
+              type: file string
+            - name: language
+              paramType: form
+              type: file string
+        responseMessages:
+            - code: 202
+              message: Accepted
         """
-
         return super(APIDocumentListView, self).post(*args, **kwargs)