Merge pull request #45354 from nextcloud/docs/taskprocessingapi/cleanup-endpoint-descriptions

2 files changed, 38 insertions, 46 deletions

diff --git a/core/Controller/TaskProcessingApiController.php b/core/Controller/TaskProcessingApiController.php
index ce89ebd34bb..9783299bccb 100644
--- a/core/Controller/TaskProcessingApiController.php
+++ b/core/Controller/TaskProcessingApiController.php
@@ -35,14 +35,10 @@ use OCP\AppFramework\Http\Attribute\PublicPage;
 use OCP\AppFramework\Http\Attribute\UserRateLimit;
 use OCP\AppFramework\Http\DataDownloadResponse;
 use OCP\AppFramework\Http\DataResponse;
-use OCP\Common\Exception\NotFoundException;
 use OCP\Files\File;
-use OCP\Files\GenericFileException;
 use OCP\Files\IRootFolder;
-use OCP\Files\NotPermittedException;
 use OCP\IL10N;
 use OCP\IRequest;
-use OCP\Lock\LockedException;
 use OCP\TaskProcessing\EShapeType;
 use OCP\TaskProcessing\Exception\Exception;
 use OCP\TaskProcessing\Exception\UnauthorizedException;
@@ -67,7 +63,7 @@ class TaskProcessingApiController extends \OCP\AppFramework\OCSController {
 	}
 
 	/**
-	 * This endpoint returns all available TaskProcessing task types
+	 * Returns all available TaskProcessing task types
 	 *
 	 * @return DataResponse<Http::STATUS_OK, array{types: array<string, CoreTaskProcessingTaskType>}, array{}>
 	 *
@@ -100,7 +96,7 @@ class TaskProcessingApiController extends \OCP\AppFramework\OCSController {
 	}
 
 	/**
-	 * This endpoint allows scheduling a task
+	 * Schedules a task
 	 *
 	 * @param array<string, mixed> $input Task's input parameters
 	 * @param string $type Type of the task
@@ -141,7 +137,8 @@ class TaskProcessingApiController extends \OCP\AppFramework\OCSController {
 	}
 
 	/**
-	 * This endpoint allows checking the status and results of a task.
+	 * Gets a task including status and result
+	 *
 	 * Tasks are removed 1 week after receiving their last update
 	 *
 	 * @param int $id The id of the task
@@ -163,7 +160,7 @@ class TaskProcessingApiController extends \OCP\AppFramework\OCSController {
 			return new DataResponse([
 				'task' => $json,
 			]);
-		} catch (NotFoundException $e) {
+		} catch (\OCP\TaskProcessing\Exception\NotFoundException $e) {
 			return new DataResponse(['message' => $this->l->t('Task not found')], Http::STATUS_NOT_FOUND);
 		} catch (\RuntimeException $e) {
 			return new DataResponse(['message' => $this->l->t('Internal error')], Http::STATUS_INTERNAL_SERVER_ERROR);
@@ -171,13 +168,13 @@ class TaskProcessingApiController extends \OCP\AppFramework\OCSController {
 	}
 
 	/**
-	 * This endpoint allows to delete a scheduled task for a user
+	 * Deletes a task
 	 *
 	 * @param int $id The id of the task
 	 *
 	 * @return DataResponse<Http::STATUS_OK, null, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR, array{message: string}, array{}>
 	 *
-	 * 200: Task returned
+	 * 200: Task deleted
 	 */
 	#[NoAdminRequired]
 	#[ApiRoute(verb: 'DELETE', url: '/task/{id}', root: '/taskprocessing')]
@@ -197,14 +194,13 @@ class TaskProcessingApiController extends \OCP\AppFramework\OCSController {
 
 
 	/**
-	 * This endpoint returns a list of tasks of a user that are related
-	 * with a specific appId and optionally with an identifier
+	 * Returns tasks for the current user filtered by the appId and optional customId
 	 *
 	 * @param string $appId ID of the app
 	 * @param string|null $customId An arbitrary identifier for the task
 	 * @return DataResponse<Http::STATUS_OK, array{tasks: CoreTaskProcessingTask[]}, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR, array{message: string}, array{}>
 	 *
-	 *  200: Task list returned
+	 *  200: Tasks returned
 	 */
 	#[NoAdminRequired]
 	#[ApiRoute(verb: 'GET', url: '/tasks/app/{appId}', root: '/taskprocessing')]
@@ -221,24 +217,21 @@ class TaskProcessingApiController extends \OCP\AppFramework\OCSController {
 			]);
 		} catch (Exception $e) {
 			return new DataResponse(['message' => $this->l->t('Internal error')], Http::STATUS_INTERNAL_SERVER_ERROR);
-		} catch (\JsonException $e) {
-			return new DataResponse(['message' => $this->l->t('Internal error')], Http::STATUS_INTERNAL_SERVER_ERROR);
 		}
 	}
 
 	/**
-	 * This endpoint returns a list of tasks of a user that are related
-	 * with a specific appId and optionally with an identifier
+	 * Returns tasks for the current user filtered by the optional taskType and optional customId
 	 *
 	 * @param string|null $taskType The task type to filter by
 	 * @param string|null $customId An arbitrary identifier for the task
 	 * @return DataResponse<Http::STATUS_OK, array{tasks: CoreTaskProcessingTask[]}, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR, array{message: string}, array{}>
 	 *
-	 *  200: Task list returned
+	 *  200: Tasks returned
 	 */
 	#[NoAdminRequired]
 	#[ApiRoute(verb: 'GET', url: '/tasks', root: '/taskprocessing')]
-	public function listTasksByUser(?string $taskType, ?string $customId = null): DataResponse {
+	public function listTasks(?string $taskType, ?string $customId = null): DataResponse {
 		try {
 			$tasks = $this->taskProcessingManager->getUserTasks($this->userId, $taskType, $customId);
 			/** @var CoreTaskProcessingTask[] $json */
@@ -251,13 +244,11 @@ class TaskProcessingApiController extends \OCP\AppFramework\OCSController {
 			]);
 		} catch (Exception $e) {
 			return new DataResponse(['message' => $this->l->t('Internal error')], Http::STATUS_INTERNAL_SERVER_ERROR);
-		} catch (\JsonException $e) {
-			return new DataResponse(['message' => $this->l->t('Internal error')], Http::STATUS_INTERNAL_SERVER_ERROR);
 		}
 	}
 
 	/**
-	 * This endpoint returns the contents of a file referenced in a task
+	 * Returns the contents of a file referenced in a task
 	 *
 	 * @param int $taskId The id of the task
 	 * @param int $fileId The file id of the file to retrieve
@@ -288,7 +279,7 @@ class TaskProcessingApiController extends \OCP\AppFramework\OCSController {
 			return new Http\DataDownloadResponse($node->getContent(), $node->getName(), $node->getMimeType());
 		} catch (\OCP\TaskProcessing\Exception\NotFoundException $e) {
 			return new DataResponse(['message' => $this->l->t('Not found')], Http::STATUS_NOT_FOUND);
-		} catch (GenericFileException|NotPermittedException|LockedException|Exception $e) {
+		} catch (Exception $e) {
 			return new DataResponse(['message' => $this->l->t('Internal error')], Http::STATUS_INTERNAL_SERVER_ERROR);
 		}
 	}
@@ -333,13 +324,13 @@ class TaskProcessingApiController extends \OCP\AppFramework\OCSController {
 	}
 
 	/**
-	 * This endpoint sets the task progress
+	 * Sets the task progress
 	 *
 	 * @param int $taskId The id of the task
 	 * @param float $progress The progress
 	 * @return DataResponse<Http::STATUS_OK, array{task: CoreTaskProcessingTask}, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR|Http::STATUS_NOT_FOUND, array{message: string}, array{}>
 	 *
-	 *  200: File content returned
+	 *  200: Progress updated successfully
 	 *  404: Task not found
 	 */
 	#[NoAdminRequired]
@@ -363,14 +354,14 @@ class TaskProcessingApiController extends \OCP\AppFramework\OCSController {
 	}
 
 	/**
-	 * This endpoint sets the task progress
+	 * Sets the task result
 	 *
 	 * @param int $taskId The id of the task
 	 * @param array<string,mixed>|null $output The resulting task output
 	 * @param string|null $errorMessage An error message if the task failed
 	 * @return DataResponse<Http::STATUS_OK, array{task: CoreTaskProcessingTask}, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR|Http::STATUS_NOT_FOUND, array{message: string}, array{}>
 	 *
-	 *  200: File content returned
+	 *  200: Result updated successfully
 	 *  404: Task not found
 	 */
 	#[NoAdminRequired]
@@ -397,12 +388,12 @@ class TaskProcessingApiController extends \OCP\AppFramework\OCSController {
 	}
 
 	/**
-	 * This endpoint cancels a task
+	 * Cancels a task
 	 *
 	 * @param int $taskId The id of the task
 	 * @return DataResponse<Http::STATUS_OK, array{task: CoreTaskProcessingTask}, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR|Http::STATUS_NOT_FOUND, array{message: string}, array{}>
 	 *
-	 *  200: File content returned
+	 *  200: Task canceled successfully
 	 *  404: Task not found
 	 */
 	#[NoAdminRequired]
diff --git a/core/openapi.json b/core/openapi.json
index b6268ac1317..a20691046fa 100644
--- a/core/openapi.json
+++ b/core/openapi.json
@@ -3345,7 +3345,7 @@
         "/ocs/v2.php/taskprocessing/tasktypes": {
             "get": {
                 "operationId": "task_processing_api-task-types",
-                "summary": "This endpoint returns all available TaskProcessing task types",
+                "summary": "Returns all available TaskProcessing task types",
                 "tags": [
                     "task_processing_api"
                 ],
@@ -3418,7 +3418,7 @@
         "/ocs/v2.php/taskprocessing/schedule": {
             "post": {
                 "operationId": "task_processing_api-schedule",
-                "summary": "This endpoint allows scheduling a task",
+                "summary": "Schedules a task",
                 "tags": [
                     "task_processing_api"
                 ],
@@ -3676,7 +3676,8 @@
         "/ocs/v2.php/taskprocessing/task/{id}": {
             "get": {
                 "operationId": "task_processing_api-get-task",
-                "summary": "This endpoint allows checking the status and results of a task. Tasks are removed 1 week after receiving their last update",
+                "summary": "Gets a task including status and result",
+                "description": "Tasks are removed 1 week after receiving their last update",
                 "tags": [
                     "task_processing_api"
                 ],
@@ -3830,7 +3831,7 @@
             },
             "delete": {
                 "operationId": "task_processing_api-delete-task",
-                "summary": "This endpoint allows to delete a scheduled task for a user",
+                "summary": "Deletes a task",
                 "tags": [
                     "task_processing_api"
                 ],
@@ -3866,7 +3867,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "Task returned",
+                        "description": "Task deleted",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -3939,7 +3940,7 @@
         "/ocs/v2.php/taskprocessing/tasks/app/{appId}": {
             "get": {
                 "operationId": "task_processing_api-list-tasks-by-app",
-                "summary": "This endpoint returns a list of tasks of a user that are related with a specific appId and optionally with an identifier",
+                "summary": "Returns tasks for the current user filtered by the appId and optional customId",
                 "tags": [
                     "task_processing_api"
                 ],
@@ -3983,7 +3984,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "Task list returned",
+                        "description": "Tasks returned",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -4066,8 +4067,8 @@
         },
         "/ocs/v2.php/taskprocessing/tasks": {
             "get": {
-                "operationId": "task_processing_api-list-tasks-by-user",
-                "summary": "This endpoint returns a list of tasks of a user that are related with a specific appId and optionally with an identifier",
+                "operationId": "task_processing_api-list-tasks",
+                "summary": "Returns tasks for the current user filtered by the optional taskType and optional customId",
                 "tags": [
                     "task_processing_api"
                 ],
@@ -4111,7 +4112,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "Task list returned",
+                        "description": "Tasks returned",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -4195,7 +4196,7 @@
         "/ocs/v2.php/taskprocessing/tasks/{taskId}/file/{fileId}": {
             "get": {
                 "operationId": "task_processing_api-get-file-contents",
-                "summary": "This endpoint returns the contents of a file referenced in a task",
+                "summary": "Returns the contents of a file referenced in a task",
                 "tags": [
                     "task_processing_api"
                 ],
@@ -4333,7 +4334,7 @@
         "/ocs/v2.php/taskprocessing/tasks/{taskId}/progress": {
             "post": {
                 "operationId": "task_processing_api-set-progress",
-                "summary": "This endpoint sets the task progress",
+                "summary": "Sets the task progress",
                 "tags": [
                     "task_processing_api"
                 ],
@@ -4379,7 +4380,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "File content returned",
+                        "description": "Progress updated successfully",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -4498,7 +4499,7 @@
         "/ocs/v2.php/taskprocessing/tasks/{taskId}/result": {
             "post": {
                 "operationId": "task_processing_api-set-result",
-                "summary": "This endpoint sets the task progress",
+                "summary": "Sets the task result",
                 "tags": [
                     "task_processing_api"
                 ],
@@ -4552,7 +4553,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "File content returned",
+                        "description": "Result updated successfully",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -4671,7 +4672,7 @@
         "/ocs/v2.php/taskprocessing/tasks/{taskId}/cancel": {
             "post": {
                 "operationId": "task_processing_api-cancel-task",
-                "summary": "This endpoint cancels a task",
+                "summary": "Cancels a task",
                 "tags": [
                     "task_processing_api"
                 ],
@@ -4707,7 +4708,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "File content returned",
+                        "description": "Task canceled successfully",
                         "content": {
                             "application/json": {
                                 "schema": {