From 79e153735c113e21188f51f9e4bcdab439fa1811 Mon Sep 17 00:00:00 2001 From: provokateurin Date: Thu, 16 May 2024 12:33:15 +0200 Subject: [PATCH 1/4] docs(TaskProcessingApi): Fix result endpoint description Signed-off-by: provokateurin --- core/Controller/TaskProcessingApiController.php | 2 +- core/openapi.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/core/Controller/TaskProcessingApiController.php b/core/Controller/TaskProcessingApiController.php index ce89ebd34bbf2..71d7f49a3db23 100644 --- a/core/Controller/TaskProcessingApiController.php +++ b/core/Controller/TaskProcessingApiController.php @@ -363,7 +363,7 @@ public function setProgress(int $taskId, float $progress): DataResponse { } /** - * This endpoint sets the task progress + * This endpoint sets the task result * * @param int $taskId The id of the task * @param array|null $output The resulting task output diff --git a/core/openapi.json b/core/openapi.json index 7563406dba073..65784397227ef 100644 --- a/core/openapi.json +++ b/core/openapi.json @@ -4498,7 +4498,7 @@ "/ocs/v2.php/taskprocessing/tasks/{taskId}/result": { "post": { "operationId": "task_processing_api-set-result", - "summary": "This endpoint sets the task progress", + "summary": "This endpoint sets the task result", "tags": [ "task_processing_api" ], From eabbb731730e228a9295f8fbfb613a1934f7f839 Mon Sep 17 00:00:00 2001 From: provokateurin Date: Thu, 16 May 2024 12:43:09 +0200 Subject: [PATCH 2/4] docs(TaskProcessingApi): Cleanup endpoint descriptions Signed-off-by: provokateurin --- .../TaskProcessingApiController.php | 25 +++++++++---------- core/openapi.json | 23 +++++++++-------- 2 files changed, 24 insertions(+), 24 deletions(-) diff --git a/core/Controller/TaskProcessingApiController.php b/core/Controller/TaskProcessingApiController.php index 71d7f49a3db23..5b2e1d24dfa6c 100644 --- a/core/Controller/TaskProcessingApiController.php +++ b/core/Controller/TaskProcessingApiController.php @@ -67,7 +67,7 @@ public function __construct( } /** - * This endpoint returns all available TaskProcessing task types + * Returns all available TaskProcessing task types * * @return DataResponse}, array{}> * @@ -100,7 +100,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 +141,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 @@ -171,7 +172,7 @@ 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 * @@ -197,8 +198,7 @@ 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 @@ -227,8 +227,7 @@ public function listTasksByApp(string $appId, ?string $customId = null): DataRes } /** - * 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 @@ -238,7 +237,7 @@ public function listTasksByApp(string $appId, ?string $customId = null): DataRes */ #[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 */ @@ -257,7 +256,7 @@ public function listTasksByUser(?string $taskType, ?string $customId = null): Da } /** - * 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 @@ -333,7 +332,7 @@ 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 @@ -363,7 +362,7 @@ public function setProgress(int $taskId, float $progress): DataResponse { } /** - * This endpoint sets the task result + * Sets the task result * * @param int $taskId The id of the task * @param array|null $output The resulting task output @@ -397,7 +396,7 @@ 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 diff --git a/core/openapi.json b/core/openapi.json index 65784397227ef..44ffaff60fae4 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" ], @@ -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" ], @@ -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" ], @@ -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" ], @@ -4498,7 +4499,7 @@ "/ocs/v2.php/taskprocessing/tasks/{taskId}/result": { "post": { "operationId": "task_processing_api-set-result", - "summary": "This endpoint sets the task result", + "summary": "Sets the task result", "tags": [ "task_processing_api" ], @@ -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" ], From 4c375c98a464c382c5a019d4716c88fce33b9ffc Mon Sep 17 00:00:00 2001 From: provokateurin Date: Thu, 16 May 2024 14:56:12 +0200 Subject: [PATCH 3/4] docs(TaskProcessingApi): Set correct status code messages Signed-off-by: provokateurin --- core/Controller/TaskProcessingApiController.php | 12 ++++++------ core/openapi.json | 12 ++++++------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/core/Controller/TaskProcessingApiController.php b/core/Controller/TaskProcessingApiController.php index 5b2e1d24dfa6c..00551b5d3e27c 100644 --- a/core/Controller/TaskProcessingApiController.php +++ b/core/Controller/TaskProcessingApiController.php @@ -178,7 +178,7 @@ public function getTask(int $id): DataResponse { * * @return DataResponse|DataResponse * - * 200: Task returned + * 200: Task deleted */ #[NoAdminRequired] #[ApiRoute(verb: 'DELETE', url: '/task/{id}', root: '/taskprocessing')] @@ -204,7 +204,7 @@ public function deleteTask(int $id): DataResponse { * @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')] @@ -233,7 +233,7 @@ public function listTasksByApp(string $appId, ?string $customId = null): DataRes * @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')] @@ -338,7 +338,7 @@ private function extractFileIdsFromTask(Task $task): array { * @param float $progress The progress * @return DataResponse|DataResponse * - * 200: File content returned + * 200: Progress updated successfully * 404: Task not found */ #[NoAdminRequired] @@ -369,7 +369,7 @@ public function setProgress(int $taskId, float $progress): DataResponse { * @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] @@ -401,7 +401,7 @@ public function setResult(int $taskId, ?array $output = null, ?string $errorMess * @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 44ffaff60fae4..a705afde19ef6 100644 --- a/core/openapi.json +++ b/core/openapi.json @@ -3867,7 +3867,7 @@ ], "responses": { "200": { - "description": "Task returned", + "description": "Task deleted", "content": { "application/json": { "schema": { @@ -3984,7 +3984,7 @@ ], "responses": { "200": { - "description": "Task list returned", + "description": "Tasks returned", "content": { "application/json": { "schema": { @@ -4112,7 +4112,7 @@ ], "responses": { "200": { - "description": "Task list returned", + "description": "Tasks returned", "content": { "application/json": { "schema": { @@ -4380,7 +4380,7 @@ ], "responses": { "200": { - "description": "File content returned", + "description": "Progress updated successfully", "content": { "application/json": { "schema": { @@ -4553,7 +4553,7 @@ ], "responses": { "200": { - "description": "File content returned", + "description": "Result updated successfully", "content": { "application/json": { "schema": { @@ -4708,7 +4708,7 @@ ], "responses": { "200": { - "description": "File content returned", + "description": "Task canceled successfully", "content": { "application/json": { "schema": { From a8abe9d3c231d0f77b8b5f6f81469caa89011a49 Mon Sep 17 00:00:00 2001 From: provokateurin Date: Thu, 16 May 2024 14:56:46 +0200 Subject: [PATCH 4/4] fix(TaskProcessingApi): Cleanup error handling Signed-off-by: provokateurin --- core/Controller/TaskProcessingApiController.php | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/core/Controller/TaskProcessingApiController.php b/core/Controller/TaskProcessingApiController.php index 00551b5d3e27c..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; @@ -164,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); @@ -221,8 +217,6 @@ 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); } } @@ -250,8 +244,6 @@ public function listTasks(?string $taskType, ?string $customId = null): DataResp ]); } 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); } } @@ -287,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); } }