From 6b424b0eb14c56c500a443c538fac0e563bb1fed Mon Sep 17 00:00:00 2001
From: Roberto Rosario <roberto.rosario.gonzalez@gmail.com>
Date: Tue, 4 Jul 2017 20:23:30 -0400
Subject: [PATCH] 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>
---
 docs/releases/2.5.rst             |  5 ++--
 mayan/apps/documents/api_views.py | 38 +++++++++++++++++++++++++++----
 2 files changed, 36 insertions(+), 7 deletions(-)

diff --git a/docs/releases/2.5.rst b/docs/releases/2.5.rst
index b6a37a76ca..4a82e8e30a 100644
--- a/docs/releases/2.5.rst
+++ b/docs/releases/2.5.rst
@@ -38,7 +38,8 @@ Other Changes
   settings. These setting have been consolidated into
   CONVERTER_GRAPHICS_BACKEND_CONFIG.
 - PDF compatibility improvements.
-
+- Improve the documentation of the document creation API endpoint.
+  GitHub issue #255. Thanks to @lcerliani opening the issue.
 
 Removals
 --------
@@ -93,8 +94,8 @@ Backward incompatible changes
 Bugs fixed or issues closed
 ===========================
 
+* `GitHub issue #255 <https://github.com/mayan-edms/mayan-edms/issues/255>`_ Uploading a local file via api
 * `GitLab issue #215 <https://gitlab.com/mayan-edms/mayan-edms/issues/215>`_ Download text contents
 * `GitLab issue #286 <https://gitlab.com/mayan-edms/mayan-edms/issues/286>`_ User configurable mailer
 
-
 .. _PyPI: https://pypi.python.org/pypi/mayan-edms/
diff --git a/mayan/apps/documents/api_views.py b/mayan/apps/documents/api_views.py
index 99d2d90d1e..a8ae03d5db 100644
--- a/mayan/apps/documents/api_views.py
+++ b/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)