zou 0.20.83__py3-none-any.whl → 0.20.85__py3-none-any.whl

zou/app/blueprints/tasks/resources.py

@@ -33,17 +33,17 @@ from zou.app.mixin import ArgsMixin
 
 
 class AddPreviewResource(Resource, ArgsMixin):
+
     @jwt_required()
     def post(self, task_id, comment_id):
         """
-        Add preview metadata to given task. The preview file itself should be
-        uploaded afterward.
-
-        Revision is automatically set: it is equal to last revision + 1. It can
-        be also set manually.
+        Add task preview
         ---
         tags:
         - Tasks
+        description: Add preview metadata to a task. The preview file is
+          uploaded after. Revision is auto set to last + 1. It can also be set
+          manually.
         parameters:
           - in: path
             name: task_id
@@ -72,15 +72,37 @@ class AddPreviewResource(Resource, ArgsMixin):
                     example: 1
         responses:
             201:
-              description: Preview metadata added to given task
+              description: Preview metadata added to task
               content:
                 application/json:
                   schema:
                     type: object
+                    properties:
+                      id:
+                        type: string
+                        format: uuid
+                        example: b24a6ea4-ce75-4665-a070-57453082c25
+                      comment_id:
+                        type: string
+                        format: uuid
+                        example: a24a6ea4-ce75-4665-a070-57453082c25
+                      task_id:
+                        type: string
+                        format: uuid
+                        example: c24a6ea4-ce75-4665-a070-57453082c25
+                      revision:
+                        type: integer
+                        example: 3
+                      person_id:
+                        type: string
+                        format: uuid
+                        example: d24a6ea4-ce75-4665-a070-57453082c25
+                      created_at:
+                        type: string
+                        format: date-time
+                        example: "2024-01-15T10:30:00Z"
             400:
               description: Bad request
-            404:
-              description: Task or comment not found
         """
         args = self.get_args([("revision", 0, False, int)])
 
@@ -94,17 +116,16 @@ class AddPreviewResource(Resource, ArgsMixin):
 
 
 class AddExtraPreviewResource(Resource, ArgsMixin):
-    """
-    Add a preview to given comment.
-    """
 
     @jwt_required()
     def post(self, task_id, comment_id, preview_file_id):
         """
-        Add a preview to given comment.
+        Add preview to comment
         ---
         tags:
         - Tasks
+        description: Add a preview to a comment by uploading a file in multipart
+          form data.
         parameters:
           - in: path
             name: task_id
@@ -140,15 +161,33 @@ class AddExtraPreviewResource(Resource, ArgsMixin):
                     description: Preview file to upload
         responses:
             201:
-              description: Preview added to given comment
+              description: Preview added to comment
               content:
                 application/json:
                   schema:
                     type: object
+                    properties:
+                      id:
+                        type: string
+                        format: uuid
+                        example: b24a6ea4-ce75-4665-a070-57453082c25
+                      comment_id:
+                        type: string
+                        format: uuid
+                        example: a24a6ea4-ce75-4665-a070-57453082c25
+                      task_id:
+                        type: string
+                        format: uuid
+                        example: c24a6ea4-ce75-4665-a070-57453082c25
+                      revision:
+                        type: integer
+                        example: 2
+                      person_id:
+                        type: string
+                        format: uuid
+                        example: d24a6ea4-ce75-4665-a070-57453082c25
             400:
               description: Bad request
-            404:
-              description: Task, comment, or preview file not found
         """
         user_service.check_task_action_access(task_id)
         tasks_service.get_comment(comment_id)
@@ -164,10 +203,12 @@ class AddExtraPreviewResource(Resource, ArgsMixin):
     @jwt_required()
     def delete(self, task_id, comment_id, preview_file_id):
         """
-        Delete preview from given comment.
+        Delete preview from comment
         ---
         tags:
         - Tasks
+        description: Delete a preview from a comment. Use force query to delete
+          even if there are dependencies.
         parameters:
           - in: path
             name: task_id
@@ -199,9 +240,7 @@ class AddExtraPreviewResource(Resource, ArgsMixin):
             description: Force deletion even if preview has dependencies
         responses:
             204:
-              description: Preview deleted from given comment
-            404:
-              description: Task, comment, or preview file not found
+              description: Preview deleted from comment
         """
         task = tasks_service.get_task(task_id)
         user_service.check_project_access(task["project_id"])
@@ -212,17 +251,15 @@ class AddExtraPreviewResource(Resource, ArgsMixin):
 
 
 class TaskPreviewsResource(Resource):
-    """
-    Return previews linked to given task.
-    """
 
     @jwt_required()
     def get(self, task_id):
         """
-        Return previews linked to given task.
+        Get task previews
         ---
         tags:
         - Tasks
+        description: Return previews linked to a task.
         parameters:
           - in: path
             name: task_id
@@ -233,32 +270,52 @@ class TaskPreviewsResource(Resource):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-              description: Previews linked to given task
+              description: Previews linked to task
               content:
                 application/json:
                   schema:
                     type: array
                     items:
                       type: object
-            404:
-              description: Task not found
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        task_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        revision:
+                          type: integer
+                          example: 1
+                        comment_id:
+                          type: string
+                          format: uuid
+                          example: d24a6ea4-ce75-4665-a070-57453082c25
+                        person_id:
+                          type: string
+                          format: uuid
+                          example: e24a6ea4-ce75-4665-a070-57453082c25
+                        created_at:
+                          type: string
+                          format: date-time
+                          example: "2024-01-15T10:30:00Z"
         """
         user_service.check_task_access(task_id)
         return files_service.get_preview_files_for_task(task_id)
 
 
 class TaskCommentsResource(Resource):
-    """
-    Return comments linked to given task.
-    """
 
     @jwt_required()
     def get(self, task_id):
         """
-        Return comments linked to given task.
+        Get task comments
         ---
         tags:
         - Tasks
+        description: Return comments linked to a task.
         parameters:
           - in: path
             name: task_id
@@ -269,15 +326,37 @@ class TaskCommentsResource(Resource):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-              description: Comments linked to given task
+              description: Comments linked to task
               content:
                 application/json:
                   schema:
                     type: array
                     items:
                       type: object
-            404:
-              description: Task not found
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        object_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        person_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        text:
+                          type: string
+                          example: This task is progressing well
+                        created_at:
+                          type: string
+                          format: date-time
+                          example: "2024-01-15T10:30:00Z"
+                        updated_at:
+                          type: string
+                          format: date-time
+                          example: "2024-01-15T11:00:00Z"
         """
         user_service.check_task_access(task_id)
         is_client = permissions.has_client_permissions()
@@ -289,17 +368,15 @@ class TaskCommentsResource(Resource):
 
 
 class TaskCommentResource(Resource):
-    """
-    Remove given comment and update linked task accordingly.
-    """
 
     @jwt_required()
     def get(self, task_id, comment_id):
         """
-        Get comment corresponding at given ID.
+        Get comment
         ---
         tags:
         - Tasks
+        description: Get a comment by id for a task.
         parameters:
           - in: path
             name: task_id
@@ -317,13 +394,35 @@ class TaskCommentResource(Resource):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-              description: Comment corresponding at given ID
+              description: Comment found and returned
               content:
                 application/json:
                   schema:
                     type: object
-            404:
-              description: Task or comment not found
+                    properties:
+                      id:
+                        type: string
+                        format: uuid
+                        example: a24a6ea4-ce75-4665-a070-57453082c25
+                      object_id:
+                        type: string
+                        format: uuid
+                        example: b24a6ea4-ce75-4665-a070-57453082c25
+                      person_id:
+                        type: string
+                        format: uuid
+                        example: c24a6ea4-ce75-4665-a070-57453082c25
+                      text:
+                        type: string
+                        example: Review completed successfully
+                      created_at:
+                        type: string
+                        format: date-time
+                        example: "2024-01-15T10:30:00Z"
+                      updated_at:
+                        type: string
+                        format: date-time
+                        example: "2024-01-15T11:00:00Z"
         """
         comment = tasks_service.get_comment(comment_id)
         user_service.check_comment_access(comment)
@@ -353,10 +452,11 @@ class TaskCommentResource(Resource):
     @jwt_required()
     def delete(self, task_id, comment_id):
         """
-        Delete a comment corresponding at given ID.
+        Delete comment
         ---
         tags:
         - Tasks
+        description: Delete a comment by id for a task.
         parameters:
           - in: path
             name: task_id
@@ -374,9 +474,7 @@ class TaskCommentResource(Resource):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             204:
-              description: Comment corresponding at given ID deleted
-            404:
-              description: Task or comment not found
+              description: Comment deleted
         """
         comment = tasks_service.get_comment(comment_id)
         task = tasks_service.get_task(comment["object_id"])
@@ -393,18 +491,16 @@ class TaskCommentResource(Resource):
 
 
 class PersonTasksResource(Resource):
-    """
-    Return task assigned to given user of which status has is_done flag sets
-    to false.
-    """
 
     @jwt_required()
     def get(self, person_id):
         """
-        Return task assigned to given user of which status has is_done flag sets to false.
+        Get person open tasks
         ---
         tags:
         - Tasks
+        description: List tasks assigned to a person where the status is not
+          done.
         parameters:
           - in: path
             name: person_id
@@ -422,8 +518,36 @@ class PersonTasksResource(Resource):
                     type: array
                     items:
                       type: object
-            404:
-              description: Person not found
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: SH010 Animation
+                        task_type_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        task_status_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        entity_id:
+                          type: string
+                          format: uuid
+                          example: d24a6ea4-ce75-4665-a070-57453082c25
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: e24a6ea4-ce75-4665-a070-57453082c25
+                        assignees:
+                          type: array
+                          items:
+                            type: string
+                            format: uuid
+                          example: ["f24a6ea4-ce75-4665-a070-57453082c25"]
         """
         user_service.check_person_is_not_bot(person_id)
         if not permissions.has_admin_permissions():
@@ -440,18 +564,16 @@ class PersonTasksResource(Resource):
 
 
 class PersonRelatedTasksResource(Resource):
-    """
-    For all entities assigned to given person (that have at least one task
-    assigned to given person), returns all tasks for given task type.
-    """
 
     @jwt_required()
     def get(self, person_id, task_type_id):
         """
-        For all entities assigned to given person (that have at least one task assigned to given person), returns all tasks for given task type.
+        Get person tasks for type
         ---
         tags:
         - Tasks
+        description: For all entities assigned to the person, return tasks for
+          the given task type.
         parameters:
           - in: path
             name: person_id
@@ -469,15 +591,43 @@ class PersonRelatedTasksResource(Resource):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-              description: All Tasks for given task type
+              description: All tasks for the given task type
               content:
                 application/json:
                   schema:
                     type: array
                     items:
                       type: object
-            404:
-              description: Person or task type not found
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: Asset Modeling
+                        task_type_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        task_status_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        entity_id:
+                          type: string
+                          format: uuid
+                          example: d24a6ea4-ce75-4665-a070-57453082c25
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: e24a6ea4-ce75-4665-a070-57453082c25
+                        assignees:
+                          type: array
+                          items:
+                            type: string
+                            format: uuid
+                          example: ["f24a6ea4-ce75-4665-a070-57453082c25"]
         """
         user_service.check_person_is_not_bot(person_id)
         user = persons_service.get_current_user()
@@ -487,19 +637,16 @@ class PersonRelatedTasksResource(Resource):
 
 
 class PersonDoneTasksResource(Resource):
-    """
-    Return task assigned to given user of which status has is_done flag sets
-    to true. It return only tasks related to open projects.
-    """
 
     @jwt_required()
     def get(self, person_id):
         """
-        Return task assigned to given user of which status has is_done flag sets to true.
+        Get person done tasks
         ---
         tags:
         - Tasks
-        description: It return only tasks related to open projects.
+        description: Return tasks assigned to the person that are done. Only
+          tasks in open projects are returned.
         parameters:
           - in: path
             name: person_id
@@ -517,8 +664,36 @@ class PersonDoneTasksResource(Resource):
                     type: array
                     items:
                       type: object
-            404:
-              description: Person not found
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: EP01 Layout
+                        task_type_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        task_status_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        entity_id:
+                          type: string
+                          format: uuid
+                          example: d24a6ea4-ce75-4665-a070-57453082c25
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: e24a6ea4-ce75-4665-a070-57453082c25
+                        assignees:
+                          type: array
+                          items:
+                            type: string
+                            format: uuid
+                          example: ["f24a6ea4-ce75-4665-a070-57453082c25"]
         """
         user_service.check_person_is_not_bot(person_id)
         if not permissions.has_admin_permissions():
@@ -535,17 +710,16 @@ class PersonDoneTasksResource(Resource):
 
 
 class CreateShotTasksResource(Resource):
-    """
-    Create a new task for given shot and task type.
-    """
 
     @jwt_required()
     def post(self, project_id, task_type_id):
         """
-        Create a new task for given shot and task type.
+        Create shot tasks
         ---
         tags:
         - Tasks
+        description: Create tasks for shots. Provide a list of shot IDs in the
+          JSON body, or omit for all shots in the project.
         parameters:
           - in: path
             name: project_id
@@ -571,19 +745,42 @@ class CreateShotTasksResource(Resource):
                   type: string
                   format: uuid
                 description: List of shot IDs to create tasks for
+              example: ["b24a6ea4-ce75-4665-a070-57453082c25"]
         responses:
             201:
-              description: New task for given shot and task type created
+              description: Tasks created for shots
               content:
                 application/json:
                   schema:
                     type: array
                     items:
                       type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: SH010 Animation
+                        task_type_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        task_status_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        entity_id:
+                          type: string
+                          format: uuid
+                          example: d24a6ea4-ce75-4665-a070-57453082c25
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: e24a6ea4-ce75-4665-a070-57453082c25
             400:
               description: Bad request
-            404:
-              description: Project or task type not found
         """
         user_service.check_manager_project_access(project_id)
         task_type = tasks_service.get_task_type(task_type_id)
@@ -606,45 +803,77 @@ class CreateShotTasksResource(Resource):
 
 
 class CreateConceptTasksResource(Resource):
-    """
-    Create a new task for given concept and task type.
-    """
 
     @jwt_required()
     def post(self, project_id, task_type_id):
         """
-        Create a new task for given concept and task type.
+        Create concept tasks
         ---
         tags:
         - Tasks
+        description: Create tasks for concepts. Provide a list of concept IDs in
+          the JSON body, or omit for all concepts in the project.
         parameters:
           - in: path
             name: project_id
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
           - in: path
             name: task_type_id
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
+        requestBody:
+          required: true
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+                  format: uuid
+                description: List of concept IDs to create tasks for
+              example: ["b24a6ea4-ce75-4665-a070-57453082c25"]
         responses:
             201:
-              description: New task for given concept and task type created
+              description: Tasks created for concepts
               content:
                 application/json:
                   schema:
                     type: array
                     items:
                       type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: Concept Modeling
+                        task_type_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        task_status_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        entity_id:
+                          type: string
+                          format: uuid
+                          example: d24a6ea4-ce75-4665-a070-57453082c25
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: e24a6ea4-ce75-4665-a070-57453082c25
             400:
               description: Bad request
-            404:
-              description: Project or task type not found
         """
         user_service.check_project_access(project_id)
         if (
@@ -675,49 +904,84 @@ class CreateConceptTasksResource(Resource):
 
 
 class CreateEntityTasksResource(Resource):
+
     @jwt_required()
     def post(self, project_id, entity_type, task_type_id):
         """
-        Create a new task with given task type for each entity of given
-        entity type.
+        Create entity tasks
         ---
         tags:
         - Tasks
+        description: Create tasks for entities of a given type. Provide entity
+          IDs in the JSON body, or omit for all entities in the project.
         parameters:
           - in: path
             name: project_id
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
           - in: path
-            name: task_type_id
+            name: entity_type
             required: true
             schema:
               type: string
-            format: uuid
-            example: a24a6ea4-ce75-4665-a070-57453082c25
+            example: Asset
+            description: Entity type name (Asset, Sequence, etc.)
           - in: path
             name: task_type_id
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
+        requestBody:
+          required: true
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+                  format: uuid
+                description: List of entity IDs to create tasks for
+              example: ["b24a6ea4-ce75-4665-a070-57453082c25"]
         responses:
             201:
-              description: List of created tasks
+              description: Tasks created for entities
               content:
                 application/json:
                   schema:
                     type: array
                     items:
                       type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: Entity Task Name
+                        task_type_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        task_status_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        entity_id:
+                          type: string
+                          format: uuid
+                          example: d24a6ea4-ce75-4665-a070-57453082c25
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: e24a6ea4-ce75-4665-a070-57453082c25
             400:
               description: Bad request
-            404:
-              description: Project, entity type, or task type not found
         """
         user_service.check_manager_project_access(project_id)
         task_type = tasks_service.get_task_type(task_type_id)
@@ -746,45 +1010,77 @@ class CreateEntityTasksResource(Resource):
 
 
 class CreateAssetTasksResource(Resource):
-    """
-    Create a new task for given asset and task type.
-    """
 
     @jwt_required()
     def post(self, project_id, task_type_id):
         """
-        Create a new task for given asset and task type.
+        Create asset tasks
         ---
         tags:
         - Tasks
+        description: Create tasks for assets. Provide a list of asset IDs in
+          the JSON body, or omit for all assets in the project.
         parameters:
           - in: path
             name: project_id
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
           - in: path
             name: task_type_id
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
+        requestBody:
+          required: true
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+                  format: uuid
+                description: List of asset IDs to create tasks for
+              example: ["b24a6ea4-ce75-4665-a070-57453082c25"]
         responses:
             201:
-              description: New task for given asset and task type created
+              description: Tasks created for assets
               content:
                 application/json:
                   schema:
                     type: array
                     items:
                       type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: Asset Modeling
+                        task_type_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        task_status_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        entity_id:
+                          type: string
+                          format: uuid
+                          example: d24a6ea4-ce75-4665-a070-57453082c25
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: e24a6ea4-ce75-4665-a070-57453082c25
             400:
               description: Bad request
-            404:
-              description: Project or task type not found
         """
         user_service.check_manager_project_access(project_id)
         task_type = tasks_service.get_task_type(task_type_id)
@@ -806,45 +1102,77 @@ class CreateAssetTasksResource(Resource):
 
 
 class CreateEditTasksResource(Resource):
-    """
-    Create a new task for given edit and task type.
-    """
 
     @jwt_required()
     def post(self, project_id, task_type_id):
         """
-        Create a new task for given edit and task type.
+        Create edit tasks
         ---
         tags:
         - Tasks
+        description: Create tasks for edits. Provide a list of edit IDs in
+          the JSON body, or omit for all edits in the project.
         parameters:
           - in: path
             name: project_id
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
           - in: path
             name: task_type_id
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
+        requestBody:
+          required: true
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+                  format: uuid
+                description: List of edit IDs to create tasks for
+              example: ["b24a6ea4-ce75-4665-a070-57453082c25"]
         responses:
             201:
-              description: New task for given edit and task type created
+              description: Tasks created for edits
               content:
                 application/json:
                   schema:
                     type: array
                     items:
                       type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: Edit Compositing
+                        task_type_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        task_status_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        entity_id:
+                          type: string
+                          format: uuid
+                          example: d24a6ea4-ce75-4665-a070-57453082c25
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: e24a6ea4-ce75-4665-a070-57453082c25
             400:
-              description: Bad request
-            404:
-              description: Project or task type not found
+              description: Wrong criterions format
         """
         user_service.check_manager_project_access(project_id)
         task_type = tasks_service.get_task_type(task_type_id)
@@ -866,50 +1194,86 @@ class CreateEditTasksResource(Resource):
 
 
 class ToReviewResource(Resource, ArgsMixin):
-    """
-    Change a task status to "to review". It creates a new preview file entry
-    and set path from the hard disk.
-    """
 
     @jwt_required()
     def put(self, task_id):
         """
-        Change a task status to "to review".
+        Set task to review
         ---
         tags:
         - Tasks
-        description: It creates a new preview file entry and set path from the hard disk.
+        description: Create a new preview file entry and set the path from the
+          disk. Optionally change the task status.
         parameters:
           - in: path
             name: task_id
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
-          - in: body
-            name: Task
-            description: person ID, name, comment, revision and change status of task
-            schema:
+        requestBody:
+          required: true
+          content:
+            application/json:
+              schema:
                 type: object
                 properties:
-                    person_id:
-                        type: string
-                        format: uuid
-                        example: a24a6ea4-ce75-4665-a070-57453082c25
-                    comment:
-                        type: string
-                    name:
-                        type: string
-                    revision:
-                        type: integer
-                    change_status:
-                        type: boolean
+                  person_id:
+                    type: string
+                    format: uuid
+                    example: a24a6ea4-ce75-4665-a070-57453082c25
+                  comment:
+                    type: string
+                    example: Please check this version
+                  name:
+                    type: string
+                    example: main
+                  revision:
+                    type: integer
+                    example: 1
+                  change_status:
+                    type: boolean
+                    example: true
         responses:
             200:
-                description: Task status changed to "to review"
+                description: Task set to review and preview created
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: SH010 Animation
+                        task_type_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        task_status_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        entity_id:
+                          type: string
+                          format: uuid
+                          example: d24a6ea4-ce75-4665-a070-57453082c25
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: e24a6ea4-ce75-4665-a070-57453082c25
+                        assignees:
+                          type: array
+                          items:
+                            type: string
+                            format: uuid
+                          example: ["f24a6ea4-ce75-4665-a070-57453082c25"]
             400:
-                description: Given person not found
+                description: Invalid person or parameters
         """
         (
             person_id,
@@ -977,37 +1341,47 @@ class ToReviewResource(Resource, ArgsMixin):
 
 
 class ClearAssignationResource(Resource, ArgsMixin):
-    """
-    Remove all assignations set to given task.
-    """
 
     @jwt_required()
     def put(self):
         """
-        Remove all assignations set to given task.
+        Clear task assignations
         ---
         tags:
         - Tasks
-        parameters:
-          - in: body
-            name: Task
-            description: List of tasks ID and person ID
-            schema:
+        requestBody:
+          required: true
+          content:
+            application/json:
+              schema:
                 type: object
                 required:
                   - task_ids
                 properties:
-                    task_ids:
-                        type: string
-                        format: uuid
-                        example: a24a6ea4-ce75-4665-a070-57453082c25
-                    person_id:
-                        type: string
-                        format: uuid
-                        example: a24a6ea4-ce75-4665-a070-57453082c25
+                  task_ids:
+                    type: array
+                    items:
+                      type: string
+                      format: uuid
+                    example: [
+                      "a24a6ea4-ce75-4665-a070-57453082c25",
+                      "b24a6ea4-ce75-4665-a070-57453082c25"
+                    ]
+                  person_id:
+                    type: string
+                    format: uuid
+                    example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-                description: All assignations removed
+                description: Assignations removed
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: string
+                        format: uuid
+                      example: ["a24a6ea4-ce75-4665-a070-57453082c25"]
         """
         (task_ids, person_id) = self.get_arguments()
 
@@ -1043,19 +1417,16 @@ class ClearAssignationResource(Resource, ArgsMixin):
 
 
 class TasksAssignResource(Resource, ArgsMixin):
-    """
-    Assign given task lists to given person. If a given task ID is wrong,
-    it ignores it.
-    """
 
     @jwt_required()
     def put(self, person_id):
         """
-        Assign given task lists to given person.
+        Assign tasks to person
         ---
         tags:
         - Tasks
-        description: If a given task ID is wrong, it ignores it.
+        description: Assign a list of tasks to a person. Unknown task ids are
+          ignored.
         parameters:
           - in: path
             name: person_id
@@ -1064,21 +1435,65 @@ class TasksAssignResource(Resource, ArgsMixin):
               type: string
               format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
-          - in: body
-            name: Task
-            description: List of tasks ID
-            schema:
+        requestBody:
+          required: true
+          content:
+            application/json:
+              schema:
                 type: object
                 required:
                   - task_ids
                 properties:
-                    task_ids:
-                        type: string
-                        format: uuid
-                        example: a24a6ea4-ce75-4665-a070-57453082c25
+                  task_ids:
+                    type: array
+                    items:
+                      type: string
+                      format: uuid
+                    example: [
+                      "a24a6ea4-ce75-4665-a070-57453082c25",
+                      "b24a6ea4-ce75-4665-a070-57453082c25"
+                    ]
         responses:
             200:
-                description: Given tasks lists assigned to given person
+                description: Tasks assigned to person
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SH010 Animation
+                          task_type_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          task_status_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
+                          entity_id:
+                            type: string
+                            format: uuid
+                            example: d24a6ea4-ce75-4665-a070-57453082c25
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: e24a6ea4-ce75-4665-a070-57453082c25
+                          assignees:
+                            type: array
+                            items:
+                              type: string
+                              format: uuid
+                            example: ["f24a6ea4-ce75-4665-a070-57453082c25"]
+            400:
+                description: Assignee does not exist
         """
         args = self.get_args(
             [
@@ -1117,14 +1532,11 @@ class TasksAssignResource(Resource, ArgsMixin):
 
 
 class TaskAssignResource(Resource, ArgsMixin):
-    """
-    Assign given task to given person.
-    """
 
     @jwt_required()
     def put(self, task_id):
         """
-        Assign given task list to given person.
+        Assign task to person
         ---
         tags:
         - Tasks
@@ -1134,25 +1546,60 @@ class TaskAssignResource(Resource, ArgsMixin):
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
-          - in: body
-            name: Person
-            description: Person ID
-            schema:
+        requestBody:
+          required: true
+          content:
+            application/json:
+              schema:
                 type: object
                 required:
                   - person_id
                 properties:
-                    person_id:
-                        type: string
-                        format: uuid
-                        example: a24a6ea4-ce75-4665-a070-57453082c25
+                  person_id:
+                    type: string
+                    format: uuid
+                    example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-                description: Given task assigned to given person
+                description: Task assigned to person
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: SH010 Animation
+                        task_type_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        task_status_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        entity_id:
+                          type: string
+                          format: uuid
+                          example: d24a6ea4-ce75-4665-a070-57453082c25
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: e24a6ea4-ce75-4665-a070-57453082c25
+                        assignees:
+                          type: array
+                          items:
+                            type: string
+                            format: uuid
+                          example: ["f24a6ea4-ce75-4665-a070-57453082c25"]
             400:
-                description: Assignee non-existent in database
+                description: Assignee does not exist
         """
         args = self.get_args(
             [
@@ -1182,17 +1629,14 @@ class TaskAssignResource(Resource, ArgsMixin):
 
 
 class TaskFullResource(Resource):
-    """
-    Return a task with many information: full details for assignees, full
-    details for task type, full details for task status, etc.
-    """
 
     @jwt_required()
     def get(self, task_id):
         """
-        Return a task with many information.
+        Get task full
         ---
-        description: Full details for assignees, full details for task type, full details for task status, etc.
+        description: Return a task with many information. Includes full details
+          for assignees, task type, and task status.
         tags:
         - Tasks
         parameters:
@@ -1205,7 +1649,70 @@ class TaskFullResource(Resource):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-                description: Task with many information
+                description: Task with full information
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: SH010 Animation
+                        task_type_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        task_status_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        entity_id:
+                          type: string
+                          format: uuid
+                          example: d24a6ea4-ce75-4665-a070-57453082c25
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: e24a6ea4-ce75-4665-a070-57453082c25
+                        assignees:
+                          type: array
+                          items:
+                            type: object
+                            properties:
+                              id:
+                                type: string
+                                format: uuid
+                                example: f24a6ea4-ce75-4665-a070-57453082c25
+                              first_name:
+                                type: string
+                                example: John
+                              last_name:
+                                type: string
+                                example: Doe
+                        task_type:
+                          type: object
+                          properties:
+                            id:
+                              type: string
+                              format: uuid
+                              example: b24a6ea4-ce75-4665-a070-57453082c25
+                            name:
+                              type: string
+                              example: Animation
+                        task_status:
+                          type: object
+                          properties:
+                            id:
+                              type: string
+                              format: uuid
+                              example: c24a6ea4-ce75-4665-a070-57453082c25
+                            name:
+                              type: string
+                              example: In Progress
         """
         task = tasks_service.get_full_task(
             task_id, persons_service.get_current_user()["id"]
@@ -1216,18 +1723,16 @@ class TaskFullResource(Resource):
 
 
 class TaskForEntityResource(Resource):
-    """
-    Return tasks related to given entity asset, episode, sequence, shot or
-    scene.
-    """
 
     @jwt_required()
     def get(self, entity_id, task_type_id):
         """
-        Return tasks related to given entity asset, episode, sequence, shot or scene.
+        Get tasks for entity and type
         ---
         tags:
         - Tasks
+        description: Return tasks related to the entity (asset, episode,
+          sequence, shot, or scene) for a task type.
         parameters:
           - in: path
             name: entity_id
@@ -1245,7 +1750,43 @@ class TaskForEntityResource(Resource):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-                description: Tasks related to given entity asset, episode, sequence, shot or scene
+                description: Tasks related to the entity and task type
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          name:
+                            type: string
+                            example: SH010 Animation
+                          task_type_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          task_status_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
+                          entity_id:
+                            type: string
+                            format: uuid
+                            example: d24a6ea4-ce75-4665-a070-57453082c25
+                          project_id:
+                            type: string
+                            format: uuid
+                            example: e24a6ea4-ce75-4665-a070-57453082c25
+                          assignees:
+                            type: array
+                            items:
+                              type: string
+                              format: uuid
+                            example: ["f24a6ea4-ce75-4665-a070-57453082c25"]
         """
         entity = entities_service.get_entity(entity_id)
         user_service.check_project_access(entity["project_id"])
@@ -1255,14 +1796,11 @@ class TaskForEntityResource(Resource):
 
 
 class SetTimeSpentResource(Resource, ArgsMixin):
-    """
-    Set time spent by a person on a task for a given day.
-    """
 
     @jwt_required()
     def post(self, task_id, date, person_id):
         """
-        Set time spent by a person on a task for a given day.
+        Set time spent
         ---
         tags:
         - Tasks
@@ -1272,34 +1810,65 @@ class SetTimeSpentResource(Resource, ArgsMixin):
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
           - in: path
             name: date
             required: true
             schema:
               type: string
-            format: date
+              format: date
             example: "2022-07-12"
           - in: path
             name: person_id
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
-          - in: body
-            name: Duration
-            schema:
+        requestBody:
+          required: true
+          content:
+            application/json:
+              schema:
                 type: object
                 properties:
-                    duration:
-                        type: float
+                  duration:
+                    type: number
+                    example: 120
         responses:
             201:
-                description: Time spent by given person on given task for given day is set
-            404:
-                description: Wrong date format
+                description: Time spent set for the person on the task and day
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        task_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        person_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        date:
+                          type: string
+                          format: date
+                          example: "2022-07-12"
+                        duration:
+                          type: number
+                          example: 120
+                        created_at:
+                          type: string
+                          format: date-time
+                          example: "2024-01-15T10:30:00Z"
+            400:
+                description: Invalid parameters
         """
         user_service.check_person_is_not_bot(person_id)
         args = self.get_args([("duration", 0, True, int)])
@@ -1322,7 +1891,7 @@ class SetTimeSpentResource(Resource, ArgsMixin):
     @jwt_required()
     def delete(self, task_id, date, person_id):
         """
-        Delete time spent by a person on a task for a given day.
+        Delete time spent
         ---
         tags:
         - Tasks
@@ -1332,27 +1901,55 @@ class SetTimeSpentResource(Resource, ArgsMixin):
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
           - in: path
             name: date
             required: true
             schema:
               type: string
-            format: date
+              format: date
             example: "2022-07-12"
           - in: path
             name: person_id
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             201:
-                description: Time spent by given person on given task for given day is removed
-            404:
-                description: Wrong date format
+                description: Time spent removed for the person on the task
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        task_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        person_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        date:
+                          type: string
+                          format: date
+                          example: "2022-07-12"
+                        duration:
+                          type: number
+                          example: 0
+                        created_at:
+                          type: string
+                          format: date-time
+                          example: "2024-01-15T10:30:00Z"
+            400:
+                description: Invalid parameters
         """
         user_service.check_person_is_not_bot(person_id)
         try:
@@ -1370,14 +1967,11 @@ class SetTimeSpentResource(Resource, ArgsMixin):
 
 
 class AddTimeSpentResource(Resource, ArgsMixin):
-    """
-    Add given timeframe to time spent by a person on a task for a given day.
-    """
 
     @jwt_required()
     def post(self, task_id, date, person_id):
         """
-        Add given timeframe to time spent by a person on a task for a given day.
+        Add time spent
         ---
         tags:
         - Tasks
@@ -1387,34 +1981,65 @@ class AddTimeSpentResource(Resource, ArgsMixin):
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
           - in: path
             name: date
             required: true
             schema:
               type: string
-            format: date
+              format: date
             example: "2022-07-12"
           - in: path
             name: person_id
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
-          - in: body
-            name: Duration
-            schema:
+        requestBody:
+          required: true
+          content:
+            application/json:
+              schema:
                 type: object
                 properties:
-                    duration:
-                        type: float
+                  duration:
+                    type: number
+                    example: 30
         responses:
             201:
-                description: Given timeframe added to time spent by given person on given task for given day
-            404:
-                description: Wrong date format
+                description: Timeframe added to time spent
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        task_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        person_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        date:
+                          type: string
+                          format: date
+                          example: "2022-07-12"
+                        duration:
+                          type: number
+                          example: 150
+                        created_at:
+                          type: string
+                          format: date-time
+                          example: "2024-01-15T10:30:00Z"
+            400:
+                description: Invalid parameters
         """
         user_service.check_person_is_not_bot(person_id)
         args = self.get_args([("duration", 0, True, int)])
@@ -1433,14 +2058,11 @@ class AddTimeSpentResource(Resource, ArgsMixin):
 
 
 class GetTimeSpentResource(Resource):
-    """
-    Get time spent on a given task.
-    """
 
     @jwt_required()
     def get(self, task_id):
         """
-        Get time spent on a given task.
+        Get task time spent
         ---
         tags:
         - Tasks
@@ -1454,23 +2076,48 @@ class GetTimeSpentResource(Resource):
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-                description: Time spent on given task
-            404:
-                description: Wrong date format
+                description: Time spent on the task
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          task_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          person_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
+                          date:
+                            type: string
+                            format: date
+                            example: "2022-07-12"
+                          duration:
+                            type: number
+                            example: 120
+                          created_at:
+                            type: string
+                            format: date-time
+                            example: "2024-01-15T10:30:00Z"
         """
         user_service.check_task_access(task_id)
         return tasks_service.get_time_spents(task_id)
 
 
 class GetTimeSpentDateResource(Resource):
-    """
-    Get time spent on a given task and date.
-    """
 
     @jwt_required()
     def get(self, task_id, date):
         """
-        Get time spent on a given task and date.
+        Get task time spent for date
         ---
         tags:
         - Tasks
@@ -1491,9 +2138,37 @@ class GetTimeSpentDateResource(Resource):
             example: "2022-07-12"
         responses:
             200:
-                description: Time spent on given task and date
-            404:
-                description: Wrong date format
+                description: Time spent on the task for the date
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          task_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          person_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
+                          date:
+                            type: string
+                            format: date
+                            example: "2022-07-12"
+                          duration:
+                            type: number
+                            example: 120
+                          created_at:
+                            type: string
+                            format: date-time
+                            example: "2024-01-15T10:30:00Z"
         """
         try:
             user_service.check_task_access(task_id)
@@ -1503,19 +2178,16 @@ class GetTimeSpentDateResource(Resource):
 
 
 class DeleteAllTasksForTaskTypeResource(Resource):
-    """
-    Delete all tasks for a given task type and project. It's mainly used
-    when tasks are created by mistake at the beginning of the project.
-    """
 
     @jwt_required()
     def delete(self, project_id, task_type_id):
         """
-        Delete all tasks for a given task type and project.
+        Delete tasks for type
         ---
         tags:
         - Tasks
-        description: It's mainly used when tasks are created by mistake at the beginning of the project.
+        description: Delete all tasks for a task type in a project. Useful when
+          tasks were created by mistake at project start.
         parameters:
           - in: path
             name: project_id
@@ -1546,19 +2218,15 @@ class DeleteAllTasksForTaskTypeResource(Resource):
 
 
 class DeleteTasksResource(Resource):
-    """
-    Delete tasks matching id list given in parameter. See it as a way to batch
-    delete tasks.
-    """
 
     @jwt_required()
     def post(self, project_id):
         """
-        Delete tasks matching id list given in parameter.
+        Delete tasks batch
         ---
         tags:
         - Tasks
-        description: See it as a way to batch delete tasks.
+        description: Delete tasks given by id list. Useful for batch deletions.
         parameters:
           - in: path
             name: project_id
@@ -1570,6 +2238,14 @@ class DeleteTasksResource(Resource):
         responses:
             200:
                 description: Tasks matching id list given in parameter deleted
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: string
+                        format: uuid
+                      example: ["a24a6ea4-ce75-4665-a070-57453082c25"]
         """
         user_service.check_manager_project_access(project_id)
         task_ids = request.json
@@ -1580,20 +2256,17 @@ class DeleteTasksResource(Resource):
 
 
 class ProjectSubscriptionsResource(Resource):
-    """
-    Retrieve all subcriptions to tasks related to given project.
-    It's mainly used for synchronisation purpose.
-    """
 
     @jwt_required()
     @permissions.require_admin
     def get(self, project_id):
         """
-        Retrieve all subcriptions to tasks related to given project.
+        Get project subscriptions
         ---
         tags:
         - Tasks
-        description: It's mainly used for synchronisation purpose.
+        description: Retrieve all subscriptions to tasks related to a project.
+          Useful for sync.
         parameters:
           - in: path
             name: project_id
@@ -1605,26 +2278,46 @@ class ProjectSubscriptionsResource(Resource):
         responses:
             200:
                 description: All subcriptions to tasks related to given project
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          person_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          task_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
+                          created_at:
+                            type: string
+                            format: date-time
+                            example: "2024-01-15T10:30:00Z"
         """
         projects_service.get_project(project_id)
         return notifications_service.get_subscriptions_for_project(project_id)
 
 
 class ProjectNotificationsResource(Resource, ArgsMixin):
-    """
-    Retrieve all notifications related to given project.
-    It's mainly used for synchronisation purpose.
-    """
 
     @jwt_required()
     @permissions.require_admin
     def get(self, project_id):
         """
-        Retrieve all notifications to tasks related to given project.
+        Get project notifications
         ---
         tags:
         - Tasks
-        description: It's mainly used for synchronisation purpose.
+        description: Retrieve notifications for tasks related to a project.
+          Useful for sync.
         parameters:
           - in: path
             name: project_id
@@ -1636,6 +2329,52 @@ class ProjectNotificationsResource(Resource, ArgsMixin):
         responses:
             200:
                 description: All notifications to tasks related to given project
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        data:
+                          type: array
+                          items:
+                            type: object
+                            properties:
+                              id:
+                                type: string
+                                format: uuid
+                                example: a24a6ea4-ce75-4665-a070-57453082c25
+                              person_id:
+                                type: string
+                                format: uuid
+                                example: b24a6ea4-ce75-4665-a070-57453082c25
+                              task_id:
+                                type: string
+                                format: uuid
+                                example: c24a6ea4-ce75-4665-a070-57453082c25
+                              comment_id:
+                                type: string
+                                format: uuid
+                                example: d24a6ea4-ce75-4665-a070-57453082c25
+                              notification_type:
+                                type: string
+                                example: assignment
+                              created_at:
+                                type: string
+                                format: date-time
+                                example: "2024-01-15T10:30:00Z"
+                              updated_at:
+                                type: string
+                                format: date-time
+                                example: "2024-01-15T11:00:00Z"
+                        limit:
+                          type: integer
+                          example: 100
+                        page:
+                          type: integer
+                          example: 1
+                        is_more:
+                          type: boolean
+                          example: true
         """
         projects_service.get_project(project_id)
         page = self.get_page()
@@ -1645,19 +2384,15 @@ class ProjectNotificationsResource(Resource, ArgsMixin):
 
 
 class ProjectTasksResource(Resource, ArgsMixin):
-    """
-    Retrieve all tasks related to given project.
-    It's mainly used for synchronisation purpose.
-    """
 
     @jwt_required()
     def get(self, project_id):
         """
-        Retrieve all tasks related to given project.
+        Get project tasks
         ---
         tags:
         - Tasks
-        description: It's mainly used for synchronisation purpose.
+        description: Retrieve tasks related to a project. Useful for sync.
         parameters:
           - in: path
             name: project_id
@@ -1686,6 +2421,54 @@ class ProjectTasksResource(Resource, ArgsMixin):
         responses:
             200:
                 description: All tasks related to given project
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        data:
+                          type: array
+                          items:
+                            type: object
+                            properties:
+                              id:
+                                type: string
+                                format: uuid
+                                example: a24a6ea4-ce75-4665-a070-57453082c25
+                              name:
+                                type: string
+                                example: SH010 Animation
+                              task_type_id:
+                                type: string
+                                format: uuid
+                                example: b24a6ea4-ce75-4665-a070-57453082c25
+                              task_status_id:
+                                type: string
+                                format: uuid
+                                example: c24a6ea4-ce75-4665-a070-57453082c25
+                              entity_id:
+                                type: string
+                                format: uuid
+                                example: d24a6ea4-ce75-4665-a070-57453082c25
+                              project_id:
+                                type: string
+                                format: uuid
+                                example: e24a6ea4-ce75-4665-a070-57453082c25
+                              assignees:
+                                type: array
+                                items:
+                                  type: string
+                                  format: uuid
+                                example: ["f24a6ea4-ce75-4665-a070-57453082c25"]
+                        limit:
+                          type: integer
+                          example: 100
+                        page:
+                          type: integer
+                          example: 1
+                        is_more:
+                          type: boolean
+                          example: true
         """
         projects_service.get_project(project_id)
         page = self.get_page()
@@ -1697,19 +2480,16 @@ class ProjectTasksResource(Resource, ArgsMixin):
 
 
 class ProjectCommentsResource(Resource, ArgsMixin):
-    """
-    Retrieve all comments to tasks related to given project.
-    It's mainly used for synchronisation purpose.
-    """
 
     @jwt_required()
     def get(self, project_id):
         """
-        Retrieve all comments to tasks related to given project.
+        Get project comments
         ---
         tags:
         - Tasks
-        description: It's mainly used for synchronisation purpose.
+        description: Retrieve comments for tasks related to a project. Useful
+          for sync.
         parameters:
           - in: path
             name: project_id
@@ -1726,6 +2506,36 @@ class ProjectCommentsResource(Resource, ArgsMixin):
         responses:
             200:
                 description: All comments to tasks related to given project
+                content:
+                  application/json:
+                    schema:
+                      type: array
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            format: uuid
+                            example: a24a6ea4-ce75-4665-a070-57453082c25
+                          object_id:
+                            type: string
+                            format: uuid
+                            example: b24a6ea4-ce75-4665-a070-57453082c25
+                          person_id:
+                            type: string
+                            format: uuid
+                            example: c24a6ea4-ce75-4665-a070-57453082c25
+                          text:
+                            type: string
+                            example: This task looks good
+                          created_at:
+                            type: string
+                            format: date-time
+                            example: "2024-01-15T10:30:00Z"
+                          updated_at:
+                            type: string
+                            format: date-time
+                            example: "2024-01-15T11:00:00Z"
         """
         projects_service.get_project(project_id)
         user_service.check_project_access(project_id)
@@ -1740,18 +2550,18 @@ class ProjectCommentsResource(Resource, ArgsMixin):
 
 
 class ProjectPreviewFilesResource(Resource, ArgsMixin):
-    """
-    Preview files related to a given project.
-    """
 
     @jwt_required()
     @permissions.require_admin
     def get(self, project_id):
         """
-        Preview files related to a given project.
+        Get project preview files
         ---
         tags:
         - Tasks
+        description: Retrieve all preview files that are linked to a specific
+          project. This includes images, videos, and other preview media
+          associated with the project.
         parameters:
           - in: path
             name: project_id
@@ -1763,6 +2573,48 @@ class ProjectPreviewFilesResource(Resource, ArgsMixin):
         responses:
             200:
                 description: Preview files related to given project
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        data:
+                          type: array
+                          items:
+                            type: object
+                            properties:
+                              id:
+                                type: string
+                                format: uuid
+                                example: a24a6ea4-ce75-4665-a070-57453082c25
+                              task_id:
+                                type: string
+                                format: uuid
+                                example: b24a6ea4-ce75-4665-a070-57453082c25
+                              comment_id:
+                                type: string
+                                format: uuid
+                                example: c24a6ea4-ce75-4665-a070-57453082c25
+                              revision:
+                                type: integer
+                                example: 1
+                              person_id:
+                                type: string
+                                format: uuid
+                                example: e24a6ea4-ce75-4665-a070-57453082c25
+                              created_at:
+                                type: string
+                                format: date-time
+                                example: "2024-01-15T10:30:00Z"
+                        limit:
+                          type: integer
+                          example: 100
+                        page:
+                          type: integer
+                          example: 1
+                        is_more:
+                          type: boolean
+                          example: true
         """
         projects_service.get_project(project_id)
         page = self.get_page()
@@ -1773,23 +2625,55 @@ class SetTaskMainPreviewResource(Resource):
     @jwt_required()
     def put(self, task_id):
         """
-        Set last preview from given task as main preview of the related entity.
-        This preview will be used as thumbnail to illustrate the entity.
+        Set main preview from task
         ---
         tags:
           - Tasks
-        description: This preview will be used to illustrate the entity.
+        description: Set the last preview of a task as the main preview of the
+          related entity.
         parameters:
           - in: path
-            name: preview_file_id
+            name: task_id
             required: true
             schema:
               type: string
-            format: uuid
+              format: uuid
             example: a24a6ea4-ce75-4665-a070-57453082c25
         responses:
             200:
-                description: Given preview set as main preview
+                description: Preview set as main preview
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
+                        name:
+                          type: string
+                          example: SH010
+                        project_id:
+                          type: string
+                          format: uuid
+                          example: b24a6ea4-ce75-4665-a070-57453082c25
+                        preview_file_id:
+                          type: string
+                          format: uuid
+                          example: c24a6ea4-ce75-4665-a070-57453082c25
+                        entity_type_id:
+                          type: string
+                          format: uuid
+                          example: d24a6ea4-ce75-4665-a070-57453082c25
+                        created_at:
+                          type: string
+                          format: date-time
+                          example: "2024-01-15T10:30:00Z"
+                        updated_at:
+                          type: string
+                          format: date-time
+                          example: "2024-01-15T11:00:00Z"
         """
         task = tasks_service.get_task(task_id)
         user_service.check_project_access(task["project_id"])
@@ -1805,15 +2689,18 @@ class SetTaskMainPreviewResource(Resource):
 
 
 class PersonsTasksDatesResource(Resource, ArgsMixin):
+
     @jwt_required()
     @permissions.require_admin
     def get(self):
         """
-        For schedule usages, for each active person, it returns the first start
-        date of all tasks of assigned to this person and the last end date.
+        Get persons tasks dates
         ---
         tags:
         - Tasks
+        description: For each active person, return the first start date of all
+          tasks assigned to them and the last end date. Useful for schedule
+          planning.
         parameters:
           - in: query
             name: project_id
@@ -1825,7 +2712,8 @@ class PersonsTasksDatesResource(Resource, ArgsMixin):
             description: Filter by project ID
         responses:
             200:
-              description: For each person, the first start date of all tasks assigned to this person and the last end date
+              description: First start date and last end date for tasks per
+                person
               content:
                 application/json:
                   schema:
@@ -1836,14 +2724,15 @@ class PersonsTasksDatesResource(Resource, ArgsMixin):
                         person_id:
                           type: string
                           format: uuid
+                          example: a24a6ea4-ce75-4665-a070-57453082c25
                         first_start_date:
                           type: string
                           format: date
+                          example: "2024-01-15"
                         last_end_date:
                           type: string
                           format: date
-            403:
-              description: Admin permissions required
+                          example: "2024-03-21"
         """
         permissions.check_admin_permissions()
         args = self.get_args([("project_id", None, False, str)])
@@ -1853,17 +2742,16 @@ class PersonsTasksDatesResource(Resource, ArgsMixin):
 
 
 class OpenTasksResource(Resource, ArgsMixin):
-    """
-    Return all tasks related to open projects.
-    """
 
     @jwt_required()
     def get(self):
         """
-        Return all tasks related to open projects.
+        Get open tasks
         ---
         tags:
         - Tasks
+        description: Return tasks for open projects with optional filters and
+          pagination. Includes statistics.
         parameters:
           - in: query
             name: project_id
@@ -2013,15 +2901,16 @@ class OpenTasksStatsResource(Resource, ArgsMixin):
     @jwt_required()
     def get(self):
         """
-        Return task amount, task done amount, total estimation, total duration
-        by status by task type by project for open projects. It aggregates the
-        result at the project level.
+        Get open tasks stats
         ---
         tags:
         - Tasks
+        description: Return totals and aggregates by status and task type per
+          project for open projects.
         responses:
             200:
-              description: A dict organized by project that contains the results for each task type and status pairs
+              description: A dict by project with results for each task type and
+                status pair
               content:
                 application/json:
                   schema: