fix(OpenAPI): Fix all errors and add all missing docs

Signed-off-by: provokateurin <[email protected]>

composer.json

@@ -21,7 +21,7 @@
 		"cs:fix": "php-cs-fixer fix",
 		"psalm": "psalm.phar --no-cache",
 		"test:unit": "phpunit --config tests/phpunit.xml",
-		"openapi": "generate-spec --verbose --allow-missing-docs --continue-on-error"
+		"openapi": "generate-spec --verbose"
 	},
 	"repositories": [
 		{

lib/Controller/AssistantApiController.php

@@ -37,6 +37,8 @@ public function __construct(
 	 * Get all available task types that the assistant can handle.
 	 *
 	 * @return DataResponse<Http::STATUS_OK, array{types: array<AssistantTaskType>}, array{}>
+	 *
+	 * 200: Available task types returned
 	 */
 	#[NoAdminRequired]
 	#[NoCSRFRequired]
@@ -51,8 +53,11 @@ public function getAvailableTaskTypes(): DataResponse {
 	 *
 	 * This will cancel the task if needed and then delete it from the server.
 	 *
-	 * @param int $metaTaskId
+	 * @param int $metaTaskId ID of the task
 	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_NOT_FOUND, '', array{}>
+	 *
+	 * 200: Task deleted successfully
+	 * 404: Task not found
 	 */
 	#[NoAdminRequired]
 	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT, tags: ['task_management'])]
@@ -73,8 +78,11 @@ public function deleteTask(int $metaTaskId): DataResponse {
 	 *
 	 * This endpoint will prevent a scheduled task to run by unscheduling it
 	 *
-	 * @param int $metaTaskId
+	 * @param int $metaTaskId ID of the task
 	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_NOT_FOUND, '', array{}>
+	 *
+	 * 200: Task canceled successfully
+	 * 404: Task not found
 	 */
 	#[NoAdminRequired]
 	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT, tags: ['task_management'])]
@@ -95,7 +103,7 @@ public function cancelTask(int $metaTaskId): DataResponse {
 	 *
 	 * Get one specific task. It has to be a task owned by the current user.
 	 *
-	 * @param int $metaTaskId
+	 * @param int $metaTaskId ID of the task
 	 * @return DataResponse<Http::STATUS_OK, array{task: AssistantTask}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, '', array{}>
 	 *
 	 * 200: Task has been found
@@ -123,6 +131,9 @@ public function getAssistantTask(int $metaTaskId): DataResponse {
 	 * @param string|null $taskType Task type id. If null, tasks of all task types will be retrieved (default: null)
 	 * @param int|null $category Task category. If null, tasks of all categories will be retrieved (default: null)
 	 * @return DataResponse<Http::STATUS_OK, array{tasks: array<AssistantTask>}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, '', array{}>
+	 *
+	 * 200: User tasks returned
+	 * 404: No tasks found
 	 */
 	#[NoAdminRequired]
 	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT, tags: ['task_management'])]
@@ -146,11 +157,14 @@ public function getUserTasks(?string $taskType = null, ?int $category = null): D
 	 *
 	 * This endpoint will run the task synchronously.
 	 *
-	 * @param array<string, string> $inputs
+	 * @param array<string, string> $inputs Input parameters
 	 * @param string $type Task type id
 	 * @param string $appId App id to be set in the created task
 	 * @param string $identifier Identifier to be set in the created task
 	 * @return DataResponse<Http::STATUS_OK, array{task: AssistantTask}, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, string, array{}>
+	 *
+	 * 200: Task started successfully
+	 * 400: Running task is not possible
 	 */
 	#[NoAdminRequired]
 	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT, tags: ['text_processing'])]
@@ -174,11 +188,14 @@ public function runTextProcessingTask(string $type, array $inputs, string $appId
 	 *
 	 * This endpoint will schedule the task for it to run as soon as possible.
 	 *
-	 * @param array<string, string> $inputs
+	 * @param array<string, string> $inputs Input parameters
 	 * @param string $type Task type id
 	 * @param string $appId App id to be set in the created task
 	 * @param string $identifier Identifier to be set in the created task
 	 * @return DataResponse<Http::STATUS_OK, array{task: AssistantTask}, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, string, array{}>
+	 *
+	 * 200: Task scheduled
+	 * 400: Scheduling task is not possible
 	 */
 	#[NoAdminRequired]
 	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT, tags: ['text_processing'])]
@@ -204,11 +221,14 @@ public function scheduleTextProcessingTask(string $type, array $inputs, string $
 	 *
 	 * The choice between run or schedule depends on the estimated runtime declared by the actual provider that will process the task.
 	 *
-	 * @param array<string, string> $inputs
+	 * @param array<string, string> $inputs Input parameters
 	 * @param string $type Task type id
 	 * @param string $appId App id to be set in the created task
 	 * @param string $identifier Identifier to be set in the created task
 	 * @return DataResponse<Http::STATUS_OK, array{task: AssistantTask}, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, string, array{}>
+	 *
+	 * 200: Task scheduled
+	 * 400: Scheduling task is not possible
 	 */
 	#[NoAdminRequired]
 	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT, tags: ['text_processing'])]
@@ -234,6 +254,9 @@ public function runOrScheduleTextProcessingTask(string $type, array $inputs, str
 	 *
 	 * @param string $filePath Path of the file to parse in the user's storage
 	 * @return DataResponse<Http::STATUS_OK, array{parsedText: string}, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, string, array{}>
+	 *
+	 * 200: Text parsed from file successfully
+	 * 400: Parsing text from file is not possible
 	 */
 	#[NoAdminRequired]
 	public function parseTextFromFile(string $filePath): DataResponse {

lib/Controller/SpeechToTextApiController.php

@@ -90,6 +90,9 @@ public function getTranscript(int $id): DataResponse {
 	 * @throws NotFoundException
 	 * @throws NotPermittedException
 	 * @throws \OCP\DB\Exception
+	 *
+	 * 200: Task started successfully
+	 * 400: Starting task is not possible
 	 */
 	#[NoAdminRequired]
 	public function transcribeAudio(string $appId, string $identifier): DataResponse {
@@ -148,6 +151,10 @@ public function transcribeAudio(string $appId, string $identifier): DataResponse
 	 * @throws InvalidPathException
 	 * @throws NoUserException
 	 * @throws \OCP\DB\Exception
+	 *
+	 * 200: Task started successfully
+	 * 400: Starting task is not possible
+	 * 404: File not found
 	 */
 	#[NoAdminRequired]
 	public function transcribeFile(string $path, string $appId, string $identifier): DataResponse {

lib/Controller/Text2ImageApiController.php

@@ -44,12 +44,15 @@ public function __construct(
 	 *
 	 * @param string $appId App id to be set in the created task
 	 * @param string $identifier Identifier to be set in the created task
-	 * @param string $prompt
+	 * @param string $prompt Input prompt for the image
 	 * @param int $nResults Number of images to generate (default: 1)
 	 * @param bool $displayPrompt Option to include the prompt when displaying the result images (default: false)
 	 * @param bool $notifyReadyIfScheduled Whether a notification will be produced when the tasks has run if it was scheduled (default: false)
 	 * @param bool $schedule Force scheduling even if the task could run synchronously (default: false)
 	 * @return DataResponse<Http::STATUS_OK, array{task: AssistantImageProcessPromptResponse}, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
+	 *
+	 * 200: Task started successfully
+	 * 400: Starting task is not possible
 	 */
 	#[NoAdminRequired]
 	#[NoCSRFRequired]
@@ -73,11 +76,12 @@ public function processPrompt(
 	/**
 	 * Get one image of a generation
 	 *
-	 * @param string $imageGenId
-	 * @param int $fileNameId
-	 * @return DataDisplayResponse<Http::STATUS_OK, array<string, mixed>>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR|Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
+	 * @param string $imageGenId ID of the image generation
+	 * @param int $fileNameId ID of the file name
+	 * @return DataDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR|Http::STATUS_BAD_REQUEST, array{error: string}, array{}>
 	 *
 	 * 200: Returns the image data
+	 * 400: Getting image is not possible
 	 */
 	#[NoAdminRequired]
 	#[NoCSRFRequired]
@@ -104,10 +108,14 @@ public function getImage(string $imageGenId, int $fileNameId): DataDisplayRespon
 		}
 		*/
 
+		/** @var string $contentType */
+		$contentType = $result['content-type'];
+		$contentType ??= 'image/jpeg';
+
 		$response = new DataDisplayResponse(
 			$result['image'] ?? '',
 			Http::STATUS_OK,
-			['Content-Type' => $result['content-type'] ?? 'image/jpeg']
+			['Content-Type' => $contentType]
 		);
 		$response->cacheFor(60 * 60 * 24);
 		return $response;
@@ -116,7 +124,7 @@ public function getImage(string $imageGenId, int $fileNameId): DataDisplayRespon
 	/**
 	 * Get image generation information
 	 *
-	 * @param string $imageGenId
+	 * @param string $imageGenId ID of the generation info
 	 * @return DataResponse<Http::STATUS_OK, AssistantImageGenInfo, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, array{error: string}, array{}>
 	 *
 	 * 200: Returns the requested data
@@ -149,9 +157,13 @@ public function getGenerationInfo(string $imageGenId): DataResponse {
 	/**
 	 * Set visibility of images in one generation
 	 *
-	 * @param string $imageGenId
-	 * @param array<string, mixed> $fileVisStatusArray
+	 * @param string $imageGenId ID of the image generation
+	 * @param array<string, mixed> $fileVisStatusArray New file visibilities
 	 * @return DataResponse<Http::STATUS_OK, '', array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_UNAUTHORIZED|Http::STATUS_INTERNAL_SERVER_ERROR, array{error: string}, array{}>
+	 *
+	 * 200: Visiblity set successfully
+	 * 400: Setting visibility is not possible
+	 * 401: Setting visibility is not allowed
 	 */
 	#[NoAdminRequired]
 	#[NoCSRFRequired]
@@ -189,8 +201,10 @@ public function setVisibilityOfImageFiles(string $imageGenId, array $fileVisStat
 	 * as we don't want to keep the front-end waiting.
 	 * However, we still use rate limiting to prevent timing attacks.
 	 *
-	 * @param string $imageGenId
+	 * @param string $imageGenId ID of the image generation
 	 * @return DataResponse<Http::STATUS_OK, '', array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR, array{error: string}, array{}>
+	 *
+	 * 200: Ready notification enabled successfully
 	 */
 	#[NoAdminRequired]
 	#[NoCSRFRequired]
@@ -216,9 +230,11 @@ public function notifyWhenReady(string $imageGenId): DataResponse {
 	 * (In theory bruteforce may be possible by a response timing attack but the attacker
 	 * won't gain access to the generation since its deleted during the attack.)
 	 *
-	 * @param string $imageGenId
+	 * @param string $imageGenId ID of the image generation
 	 * @return DataResponse<Http::STATUS_OK, '', array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR, array{error: string}, array{}>
 	 * @throws NotPermittedException
+	 *
+	 * 200: Generation canceled successfully
 	 */
 	#[NoAdminRequired]
 	#[NoCSRFRequired]