diff --git a/core/Controller/TaskProcessingApiController.php b/core/Controller/TaskProcessingApiController.php index ce89ebd34bbf2..9783299bccb1c 100644 --- a/core/Controller/TaskProcessingApiController.php +++ b/core/Controller/TaskProcessingApiController.php @@ -35,14 +35,10 @@ 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 @@ public function __construct( } /** - * This endpoint returns all available TaskProcessing task types + * Returns all available TaskProcessing task types * * @return DataResponse}, array{}> * @@ -100,7 +96,7 @@ public function taskTypes(): DataResponse { } /** - * This endpoint allows scheduling a task + * Schedules a task * * @param array $input Task's input parameters * @param string $type Type of the task @@ -141,7 +137,8 @@ public function schedule(array $input, string $type, string $appId, string $cust } /** - * 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 @@ public function getTask(int $id): DataResponse { 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 @@ public function getTask(int $id): DataResponse { } /** - * This endpoint allows to delete a scheduled task for a user + * Deletes a task * * @param int $id The id of the task * * @return DataResponse|DataResponse * - * 200: Task returned + * 200: Task deleted */ #[NoAdminRequired] #[ApiRoute(verb: 'DELETE', url: '/task/{id}', root: '/taskprocessing')] @@ -197,14 +194,13 @@ public function deleteTask(int $id): DataResponse { /** - * 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|DataResponse * - * 200: Task list returned + * 200: Tasks returned */ #[NoAdminRequired] #[ApiRoute(verb: 'GET', url: '/tasks/app/{appId}', root: '/taskprocessing')] @@ -221,24 +217,21 @@ public function listTasksByApp(string $appId, ?string $customId = null): DataRes ]); } 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|DataResponse * - * 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 @@ public function listTasksByUser(?string $taskType, ?string $customId = null): Da ]); } 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 @@ public function getFileContents(int $taskId, int $fileId): Http\DataDownloadResp 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 @@ private function extractFileIdsFromTask(Task $task): array { } /** - * 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|DataResponse * - * 200: File content returned + * 200: Progress updated successfully * 404: Task not found */ #[NoAdminRequired] @@ -363,14 +354,14 @@ public function setProgress(int $taskId, float $progress): DataResponse { } /** - * This endpoint sets the task progress + * Sets the task result * * @param int $taskId The id of the task * @param array|null $output The resulting task output * @param string|null $errorMessage An error message if the task failed * @return DataResponse|DataResponse * - * 200: File content returned + * 200: Result updated successfully * 404: Task not found */ #[NoAdminRequired] @@ -397,12 +388,12 @@ public function setResult(int $taskId, ?array $output = null, ?string $errorMess } /** - * This endpoint cancels a task + * Cancels a task * * @param int $taskId The id of the task * @return DataResponse|DataResponse * - * 200: File content returned + * 200: Task canceled successfully * 404: Task not found */ #[NoAdminRequired] diff --git a/core/openapi.json b/core/openapi.json index b6268ac1317df..a20691046fa7a 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": {