sascha
/
nextcloud-server
mirror of https://github.com/nextcloud/server.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

feat/45085/validate-config-values
Kate 2024-05-16 20:09:06 +07:00 committed by GitHub
parent b1f9c4bfee a8abe9d3c2
commit 7bc4ccba6a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 38 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
core/Controller/TaskProcessingApiController.php
Unescape Escape View File

@ -35,14 +35,10 @@ use OCP\AppFramework\Http\Attribute\PublicPage;
use OCP\AppFramework\Http\Attribute\UserRateLimit; use OCP\AppFramework\Http\Attribute\UserRateLimit;
use OCP\AppFramework\Http\DataDownloadResponse; use OCP\AppFramework\Http\DataDownloadResponse;
use OCP\AppFramework\Http\DataResponse; use OCP\AppFramework\Http\DataResponse;
use OCP\Common\Exception\NotFoundException;
use OCP\Files\File; use OCP\Files\File;
use OCP\Files\GenericFileException;
use OCP\Files\IRootFolder; use OCP\Files\IRootFolder;
use OCP\Files\NotPermittedException;
use OCP\IL10N; use OCP\IL10N;
use OCP\IRequest; use OCP\IRequest;
use OCP\Lock\LockedException;
use OCP\TaskProcessing\EShapeType; use OCP\TaskProcessing\EShapeType;
use OCP\TaskProcessing\Exception\Exception; use OCP\TaskProcessing\Exception\Exception;
use OCP\TaskProcessing\Exception\UnauthorizedException; 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{}> * @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 array<string, mixed> $input Task's input parameters
* @param string $type Type of the task * @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 * Tasks are removed 1 week after receiving their last update
* *
* @param int $id The id of the task * @param int $id The id of the task
@ -163,7 +160,7 @@ class TaskProcessingApiController extends \OCP\AppFramework\OCSController {
return new DataResponse([ return new DataResponse([
'task' => $json, '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); return new DataResponse(['message' => $this->l->t('Task not found')], Http::STATUS_NOT_FOUND);
} catch (\RuntimeException $e) { } catch (\RuntimeException $e) {
return new DataResponse(['message' => $this->l->t('Internal error')], Http::STATUS_INTERNAL_SERVER_ERROR); 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 * @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{}> * @return DataResponse<Http::STATUS_OK, null, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR, array{message: string}, array{}>
* *
* 200: Task returned * 200: Task deleted
*/ */
#[NoAdminRequired] #[NoAdminRequired]
#[ApiRoute(verb: 'DELETE', url: '/task/{id}', root: '/taskprocessing')] #[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 * Returns tasks for the current user filtered by the appId and optional customId
* with a specific appId and optionally with an identifier
* *
* @param string $appId ID of the app * @param string $appId ID of the app
* @param string|null $customId An arbitrary identifier for the task * @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{}> * @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] #[NoAdminRequired]
#[ApiRoute(verb: 'GET', url: '/tasks/app/{appId}', root: '/taskprocessing')] #[ApiRoute(verb: 'GET', url: '/tasks/app/{appId}', root: '/taskprocessing')]
@ -221,24 +217,21 @@ class TaskProcessingApiController extends \OCP\AppFramework\OCSController {
]); ]);
} catch (Exception $e) { } catch (Exception $e) {
return new DataResponse(['message' => $this->l->t('Internal error')], Http::STATUS_INTERNAL_SERVER_ERROR); 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 * Returns tasks for the current user filtered by the optional taskType and optional customId
* with a specific appId and optionally with an identifier
* *
* @param string|null $taskType The task type to filter by * @param string|null $taskType The task type to filter by
* @param string|null $customId An arbitrary identifier for the task * @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{}> * @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] #[NoAdminRequired]
#[ApiRoute(verb: 'GET', url: '/tasks', root: '/taskprocessing')] #[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 { try {
$tasks = $this->taskProcessingManager->getUserTasks($this->userId, $taskType, $customId); $tasks = $this->taskProcessingManager->getUserTasks($this->userId, $taskType, $customId);
/** @var CoreTaskProcessingTask[] $json */ /** @var CoreTaskProcessingTask[] $json */
@ -251,13 +244,11 @@ class TaskProcessingApiController extends \OCP\AppFramework\OCSController {
]); ]);
} catch (Exception $e) { } catch (Exception $e) {
return new DataResponse(['message' => $this->l->t('Internal error')], Http::STATUS_INTERNAL_SERVER_ERROR); 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 $taskId The id of the task
* @param int $fileId The file id of the file to retrieve * @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()); return new Http\DataDownloadResponse($node->getContent(), $node->getName(), $node->getMimeType());
} catch (\OCP\TaskProcessing\Exception\NotFoundException $e) { } catch (\OCP\TaskProcessing\Exception\NotFoundException $e) {
return new DataResponse(['message' => $this->l->t('Not found')], Http::STATUS_NOT_FOUND); 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); 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 int $taskId The id of the task
* @param float $progress The progress * @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{}> * @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 * 404: Task not found
*/ */
#[NoAdminRequired] #[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 int $taskId The id of the task
* @param array<string,mixed>|null $output The resulting task output * @param array<string,mixed>|null $output The resulting task output
* @param string|null $errorMessage An error message if the task failed * @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{}> * @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 * 404: Task not found
*/ */
#[NoAdminRequired] #[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 * @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{}> * @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 * 404: Task not found
*/ */
#[NoAdminRequired] #[NoAdminRequired]

35
core/openapi.json
Unescape Escape View File

@ -3345,7 +3345,7 @@
"/ocs/v2.php/taskprocessing/tasktypes": { "/ocs/v2.php/taskprocessing/tasktypes": {
"get": { "get": {
"operationId": "task_processing_api-task-types", "operationId": "task_processing_api-task-types",
"summary": "This endpoint returns all available TaskProcessing task types", "summary": "Returns all available TaskProcessing task types",
"tags": [ "tags": [
"task_processing_api" "task_processing_api"
], ],
@ -3418,7 +3418,7 @@
"/ocs/v2.php/taskprocessing/schedule": { "/ocs/v2.php/taskprocessing/schedule": {
"post": { "post": {
"operationId": "task_processing_api-schedule", "operationId": "task_processing_api-schedule",
"summary": "This endpoint allows scheduling a task", "summary": "Schedules a task",
"tags": [ "tags": [
"task_processing_api" "task_processing_api"
], ],
@ -3676,7 +3676,8 @@
"/ocs/v2.php/taskprocessing/task/{id}": { "/ocs/v2.php/taskprocessing/task/{id}": {
"get": { "get": {
"operationId": "task_processing_api-get-task", "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": [ "tags": [
"task_processing_api" "task_processing_api"
], ],
@ -3830,7 +3831,7 @@
}, },
"delete": { "delete": {
"operationId": "task_processing_api-delete-task", "operationId": "task_processing_api-delete-task",
"summary": "This endpoint allows to delete a scheduled task for a user", "summary": "Deletes a task",
"tags": [ "tags": [
"task_processing_api" "task_processing_api"
], ],
@ -3866,7 +3867,7 @@
], ],
"responses": { "responses": {
"200": { "200": {
"description": "Task returned", "description": "Task deleted",
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
@ -3939,7 +3940,7 @@
"/ocs/v2.php/taskprocessing/tasks/app/{appId}": { "/ocs/v2.php/taskprocessing/tasks/app/{appId}": {
"get": { "get": {
"operationId": "task_processing_api-list-tasks-by-app", "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": [ "tags": [
"task_processing_api" "task_processing_api"
], ],
@ -3983,7 +3984,7 @@
], ],
"responses": { "responses": {
"200": { "200": {
"description": "Task list returned", "description": "Tasks returned",
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
@ -4066,8 +4067,8 @@
}, },
"/ocs/v2.php/taskprocessing/tasks": { "/ocs/v2.php/taskprocessing/tasks": {
"get": { "get": {
"operationId": "task_processing_api-list-tasks-by-user", "operationId": "task_processing_api-list-tasks",
"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 optional taskType and optional customId",
"tags": [ "tags": [
"task_processing_api" "task_processing_api"
], ],
@ -4111,7 +4112,7 @@
], ],
"responses": { "responses": {
"200": { "200": {
"description": "Task list returned", "description": "Tasks returned",
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
@ -4195,7 +4196,7 @@
"/ocs/v2.php/taskprocessing/tasks/{taskId}/file/{fileId}": { "/ocs/v2.php/taskprocessing/tasks/{taskId}/file/{fileId}": {
"get": { "get": {
"operationId": "task_processing_api-get-file-contents", "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": [ "tags": [
"task_processing_api" "task_processing_api"
], ],
@ -4333,7 +4334,7 @@
"/ocs/v2.php/taskprocessing/tasks/{taskId}/progress": { "/ocs/v2.php/taskprocessing/tasks/{taskId}/progress": {
"post": { "post": {
"operationId": "task_processing_api-set-progress", "operationId": "task_processing_api-set-progress",
"summary": "This endpoint sets the task progress", "summary": "Sets the task progress",
"tags": [ "tags": [
"task_processing_api" "task_processing_api"
], ],
@ -4379,7 +4380,7 @@
], ],
"responses": { "responses": {
"200": { "200": {
"description": "File content returned", "description": "Progress updated successfully",
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
@ -4498,7 +4499,7 @@
"/ocs/v2.php/taskprocessing/tasks/{taskId}/result": { "/ocs/v2.php/taskprocessing/tasks/{taskId}/result": {
"post": { "post": {
"operationId": "task_processing_api-set-result", "operationId": "task_processing_api-set-result",
"summary": "This endpoint sets the task progress", "summary": "Sets the task result",
"tags": [ "tags": [
"task_processing_api" "task_processing_api"
], ],
@ -4552,7 +4553,7 @@
], ],
"responses": { "responses": {
"200": { "200": {
"description": "File content returned", "description": "Result updated successfully",
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {
@ -4671,7 +4672,7 @@
"/ocs/v2.php/taskprocessing/tasks/{taskId}/cancel": { "/ocs/v2.php/taskprocessing/tasks/{taskId}/cancel": {
"post": { "post": {
"operationId": "task_processing_api-cancel-task", "operationId": "task_processing_api-cancel-task",
"summary": "This endpoint cancels a task", "summary": "Cancels a task",
"tags": [ "tags": [
"task_processing_api" "task_processing_api"
], ],
@ -4707,7 +4708,7 @@
], ],
"responses": { "responses": {
"200": { "200": {
"description": "File content returned", "description": "Task canceled successfully",
"content": { "content": {
"application/json": { "application/json": {
"schema": { "schema": {