Merge pull request #52 from nextcloud/enh/add-openapi-specs

Add OpenAPI specs

.gitignore

@@ -10,3 +10,4 @@ node_modules
 /composer.lock
 
 /vendor/
+/tests/.phpunit*cache

appinfo/info.xml

@@ -54,7 +54,7 @@ Known providers:
 	<version>1.0.7</version>
 	<licence>agpl</licence>
 	<author>Julien Veyssier</author>
-	<namespace>TpAssistant</namespace>
+	<namespace>Assistant</namespace>
 	<documentation>
 		<developer>https://github.com/nextcloud/assistant</developer>
 	</documentation>
@@ -66,19 +66,19 @@ Known providers:
 	<screenshot>https://github.com/nextcloud/assistant/raw/main/img/screenshot3.jpg</screenshot>
 	<screenshot>https://github.com/nextcloud/assistant/raw/main/img/screenshot4.jpg</screenshot>
 	<background-jobs>
-		<job>OCA\TpAssistant\Cron\CleanupImageGenerations</job>
-		<job>OCA\TpAssistant\Cron\CleanupAssistantTasks</job>
+		<job>OCA\Assistant\Cron\CleanupImageGenerations</job>
+		<job>OCA\Assistant\Cron\CleanupAssistantTasks</job>
 	</background-jobs>
 	<commands>
-		<command>OCA\TpAssistant\Command\CleanupImageGenerations</command>
-		<command>OCA\TpAssistant\Command\CleanupAssistantTasks</command>
+		<command>OCA\Assistant\Command\CleanupImageGenerations</command>
+		<command>OCA\Assistant\Command\CleanupAssistantTasks</command>
 	</commands>
 	<dependencies>
 		<nextcloud min-version="28" max-version="29"/>
 	</dependencies>
 	<settings>
-		<admin>OCA\TpAssistant\Settings\Admin</admin>
-		<personal>OCA\TpAssistant\Settings\Personal</personal>
-		<personal-section>OCA\TpAssistant\Settings\PersonalSection</personal-section>
+		<admin>OCA\Assistant\Settings\Admin</admin>
+		<personal>OCA\Assistant\Settings\Personal</personal>
+		<personal-section>OCA\Assistant\Settings\PersonalSection</personal-section>
 	</settings>
 </info>

appinfo/routes.php

@@ -13,6 +13,7 @@
 		['name' => 'assistant#getAssistantTaskResultPage', 'url' => '/task/view/{metaTaskId}', 'verb' => 'GET'],
 
 		['name' => 'Text2Image#showGenerationPage', 'url' => '/i/{imageGenId}', 'verb' => 'GET'],
+		['name' => 'Text2Image#getPromptHistory', 'url' => '/i/prompt_history', 'verb' => 'GET'],
 
 		['name' => 'FreePrompt#processPrompt', 'url' => '/f/process_prompt', 'verb' => 'POST'],
 		['name' => 'FreePrompt#getPromptHistory', 'url' => '/f/prompt_history', 'verb' => 'GET'],
@@ -35,7 +36,6 @@
 		['name' => 'assistantApi#cancelTask', 'url' => '/api/{apiVersion}/task/cancel/{metaTaskId}', 'verb' => 'PUT', 'requirements' => $requirements],
 
 		['name' => 'Text2ImageApi#processPrompt', 'url' => '/api/{apiVersion}/i/process_prompt', 'verb' => 'POST', 'requirements' => $requirements],
-		['name' => 'Text2ImageApi#getPromptHistory', 'url' => '/api/{apiVersion}/i/prompt_history', 'verb' => 'GET', 'requirements' => $requirements],
 		['name' => 'Text2ImageApi#getGenerationInfo', 'url' => '/api/{apiVersion}/i/info/{imageGenId}', 'verb' => 'GET', 'requirements' => $requirements],
 		['name' => 'Text2ImageApi#getImage', 'url' => '/api/{apiVersion}/i/{imageGenId}/{fileNameId}', 'verb' => 'GET', 'requirements' => $requirements],
 		['name' => 'Text2ImageApi#cancelGeneration', 'url' => '/api/{apiVersion}/i/cancel_generation', 'verb' => 'POST', 'requirements' => $requirements],

composer.json

@@ -11,7 +11,7 @@
 		}
 	],
 	"require": {
-		"php": "^8.0",
+		"php": "^8.1",
 		"erusev/parsedown": "^1.7",
 		"phpoffice/phpword": "^1.2"
 	},
@@ -20,20 +20,28 @@
 		"cs:check": "php-cs-fixer fix --dry-run --diff",
 		"cs:fix": "php-cs-fixer fix",
 		"psalm": "psalm.phar --no-cache",
-		"test:unit": "phpunit --config tests/phpunit.xml"
+		"test:unit": "phpunit --config tests/phpunit.xml",
+		"openapi": "generate-spec --verbose --allow-missing-docs --continue-on-error"
 	},
+	"repositories": [
+		{
+			"type": "vcs",
+			"url": "https://github.com/nextcloud/openapi-extractor"
+		}
+	],
 	"require-dev": {
 		"nextcloud/coding-standard": "^1.1",
 		"psalm/phar": "^5.16",
 		"nextcloud/ocp": "dev-master",
-		"phpunit/phpunit": "^9.5"
+		"phpunit/phpunit": "^9.5",
+		"nextcloud/openapi-extractor": "dev-main"
 	},
 	"config": {
 		"sort-packages": true,
 		"optimize-autoloader": true,
 		"platform": {
-			"php": "8.0"
+			"php": "8.1"
 		},
-		"autoloader-suffix": "TpAssistant"
+		"autoloader-suffix": "Assistant"
 	}
 }

lib/AppInfo/Application.php

@@ -1,20 +1,20 @@
 <?php
 
-namespace OCA\TpAssistant\AppInfo;
-
-use OCA\TpAssistant\Capabilities;
-use OCA\TpAssistant\Listener\BeforeTemplateRenderedListener;
-use OCA\TpAssistant\Listener\FreePrompt\FreePromptReferenceListener;
-use OCA\TpAssistant\Listener\SpeechToText\SpeechToTextReferenceListener;
-use OCA\TpAssistant\Listener\SpeechToText\SpeechToTextResultListener;
-use OCA\TpAssistant\Listener\TaskFailedListener;
-use OCA\TpAssistant\Listener\TaskSuccessfulListener;
-use OCA\TpAssistant\Listener\Text2Image\Text2ImageReferenceListener;
-use OCA\TpAssistant\Listener\Text2Image\Text2ImageResultListener;
-use OCA\TpAssistant\Notification\Notifier;
-use OCA\TpAssistant\Reference\FreePromptReferenceProvider;
-use OCA\TpAssistant\Reference\SpeechToTextReferenceProvider;
-use OCA\TpAssistant\Reference\Text2ImageReferenceProvider;
+namespace OCA\Assistant\AppInfo;
+
+use OCA\Assistant\Capabilities;
+use OCA\Assistant\Listener\BeforeTemplateRenderedListener;
+use OCA\Assistant\Listener\FreePrompt\FreePromptReferenceListener;
+use OCA\Assistant\Listener\SpeechToText\SpeechToTextReferenceListener;
+use OCA\Assistant\Listener\SpeechToText\SpeechToTextResultListener;
+use OCA\Assistant\Listener\TaskFailedListener;
+use OCA\Assistant\Listener\TaskSuccessfulListener;
+use OCA\Assistant\Listener\Text2Image\Text2ImageReferenceListener;
+use OCA\Assistant\Listener\Text2Image\Text2ImageResultListener;
+use OCA\Assistant\Notification\Notifier;
+use OCA\Assistant\Reference\FreePromptReferenceProvider;
+use OCA\Assistant\Reference\SpeechToTextReferenceProvider;
+use OCA\Assistant\Reference\Text2ImageReferenceProvider;
 use OCP\AppFramework\App;
 use OCP\AppFramework\Bootstrap\IBootContext;
 

lib/Capabilities.php

@@ -2,9 +2,9 @@
 
 declare(strict_types=1);
 
-namespace OCA\TpAssistant;
+namespace OCA\Assistant;
 
-use OCA\TpAssistant\AppInfo\Application;
+use OCA\Assistant\AppInfo\Application;
 use OCP\App\IAppManager;
 use OCP\Capabilities\IPublicCapability;
 use OCP\IConfig;

lib/Command/CleanupAssistantTasks.php

@@ -3,12 +3,12 @@
 // SPDX-FileCopyrightText: Sami Finnilä <[email protected]>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
-namespace OCA\TpAssistant\Command;
+namespace OCA\Assistant\Command;
 
 use Exception;
 use OC\Core\Command\Base;
-use OCA\TpAssistant\AppInfo\Application;
-use OCA\TpAssistant\Db\MetaTaskMapper;
+use OCA\Assistant\AppInfo\Application;
+use OCA\Assistant\Db\MetaTaskMapper;
 use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;

lib/Command/CleanupImageGenerations.php

@@ -3,12 +3,12 @@
 // SPDX-FileCopyrightText: Sami Finnilä <[email protected]>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
-namespace OCA\TpAssistant\Command;
+namespace OCA\Assistant\Command;
 
 use Exception;
 use OC\Core\Command\Base;
-use OCA\TpAssistant\AppInfo\Application;
-use OCA\TpAssistant\Service\Text2Image\CleanUpService;
+use OCA\Assistant\AppInfo\Application;
+use OCA\Assistant\Service\Text2Image\CleanUpService;
 use OCP\IConfig;
 use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;

lib/Controller/AssistantApiController.php

@@ -1,18 +1,24 @@
 <?php
 
-namespace OCA\TpAssistant\Controller;
+namespace OCA\Assistant\Controller;
 
-use OCA\TpAssistant\Db\MetaTask;
-use OCA\TpAssistant\Db\MetaTaskMapper;
-use OCA\TpAssistant\Service\AssistantService;
+use OCA\Assistant\Db\MetaTask;
+use OCA\Assistant\Db\MetaTaskMapper;
+use OCA\Assistant\ResponseDefinitions;
+use OCA\Assistant\Service\AssistantService;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\NoAdminRequired;
 use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
 use OCP\DB\Exception;
 use OCP\IRequest;
 
+/**
+ * @psalm-import-type AssistantTaskType from ResponseDefinitions
+ * @psalm-import-type AssistantTask from ResponseDefinitions
+ */
 class AssistantApiController extends OCSController {
 
 	public function __construct(
@@ -26,20 +32,26 @@ public function __construct(
 	}
 
 	/**
-	 * @return DataResponse
+	 * Get available task types
+	 *
+	 * @return DataResponse<Http::STATUS_OK, array{types: array<AssistantTaskType>}, array{}>
 	 */
 	#[NoAdminRequired]
 	#[NoCSRFRequired]
+	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT, tags: ['task_management'])]
 	public function getAvailableTaskTypes(): DataResponse {
 		$taskTypes = $this->assistantService->getAvailableTaskTypes();
 		return new DataResponse(['types' => $taskTypes]);
 	}
 
 	/**
+	 * Delete an assistant task
+	 *
 	 * @param int $metaTaskId
-	 * @return DataResponse
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_NOT_FOUND, '', array{}>
 	 */
 	#[NoAdminRequired]
+	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT, tags: ['task_management'])]
 	public function deleteTask(int $metaTaskId): DataResponse {
 		if ($this->userId !== null) {
 			try {
@@ -54,9 +66,10 @@ public function deleteTask(int $metaTaskId): DataResponse {
 
 	/**
 	 * @param int $metaTaskId
-	 * @return DataResponse
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_NOT_FOUND, '', array{}>
 	 */
 	#[NoAdminRequired]
+	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT, tags: ['task_management'])]
 	public function cancelTask(int $metaTaskId): DataResponse {
 		if ($this->userId !== null) {
 			try {
@@ -70,10 +83,16 @@ public function cancelTask(int $metaTaskId): DataResponse {
 	}
 
 	/**
+	 * Get an assistant task
+	 *
 	 * @param int $metaTaskId
-	 * @return DataResponse
+	 * @return DataResponse<Http::STATUS_OK, array{task: AssistantTask}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, '', array{}>
+	 *
+	 * 200: Task has been found
+	 * 404: Task has not been found
 	 */
 	#[NoAdminRequired]
+	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT, tags: ['task_management'])]
 	public function getAssistantTask(int $metaTaskId): DataResponse {
 		if ($this->userId !== null) {
 			$task = $this->assistantService->getAssistantTask($this->userId, $metaTaskId);
@@ -86,7 +105,15 @@ public function getAssistantTask(int $metaTaskId): DataResponse {
 		return new DataResponse('', Http::STATUS_NOT_FOUND);
 	}
 
+	/**
+	 * Get user's tasks
+	 *
+	 * @param string|null $taskType
+	 * @param int|null $category
+	 * @return DataResponse<Http::STATUS_OK, array{tasks: array<AssistantTask>}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, '', array{}>
+	 */
 	#[NoAdminRequired]
+	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT, tags: ['task_management'])]
 	public function getUserTasks(?string $taskType = null, ?int $category = null): DataResponse {
 		if ($this->userId !== null) {
 			try {
@@ -103,13 +130,16 @@ public function getUserTasks(?string $taskType = null, ?int $category = null): D
 	}
 
 	/**
-	 * @param array $inputs
+	 * Run a text processing task
+	 *
+	 * @param array<string, string> $inputs
 	 * @param string $type
 	 * @param string $appId
 	 * @param string $identifier
-	 * @return DataResponse
+	 * @return DataResponse<Http::STATUS_OK, array{task: AssistantTask}, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, string, array{}>
 	 */
 	#[NoAdminRequired]
+	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT, tags: ['text_processing'])]
 	public function runTextProcessingTask(string $type, array $inputs, string $appId, string $identifier): DataResponse {
 		if ($this->userId === null) {
 			return new DataResponse('Unknow user', Http::STATUS_BAD_REQUEST);
@@ -126,13 +156,16 @@ public function runTextProcessingTask(string $type, array $inputs, string $appId
 	}
 
 	/**
-	 * @param array $inputs
+	 * Schedule a text processing task
+	 *
+	 * @param array<string, string> $inputs
 	 * @param string $type
 	 * @param string $appId
 	 * @param string $identifier
-	 * @return DataResponse
+	 * @return DataResponse<Http::STATUS_OK, array{task: AssistantTask}, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, string, array{}>
 	 */
 	#[NoAdminRequired]
+	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT, tags: ['text_processing'])]
 	public function scheduleTextProcessingTask(string $type, array $inputs, string $appId, string $identifier): DataResponse {
 		if ($this->userId === null) {
 			return new DataResponse('Unknow user', Http::STATUS_BAD_REQUEST);
@@ -149,13 +182,18 @@ public function scheduleTextProcessingTask(string $type, array $inputs, string $
 	}
 
 	/**
-	 * @param array $inputs
+	 * Run or schedule a text processing task
+	 *
+	 * If the task runs immediately or is schedule depends on the estimated runtime declared by the provider.
+	 *
+	 * @param array<string, string> $inputs
 	 * @param string $type
 	 * @param string $appId
 	 * @param string $identifier
-	 * @return DataResponse
+	 * @return DataResponse<Http::STATUS_OK, array{task: AssistantTask}, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, string, array{}>
 	 */
 	#[NoAdminRequired]
+	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT, tags: ['text_processing'])]
 	public function runOrScheduleTextProcessingTask(string $type, array $inputs, string $appId, string $identifier): DataResponse {
 		if ($this->userId === null) {
 			return new DataResponse('Unknow user', Http::STATUS_BAD_REQUEST);
@@ -172,10 +210,12 @@ public function runOrScheduleTextProcessingTask(string $type, array $inputs, str
 	}
 
 	/**
-	 * Parse text from file (if parsing the file type is supported)
+	 * Extract text from file
+	 *
+	 * Parse and extract text content of a file (if the file type is supported)
 	 *
 	 * @param string $filePath
-	 * @return DataResponse
+	 * @return DataResponse<Http::STATUS_OK, array{parsedText: string}, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, string, array{}>
 	 */
 	#[NoAdminRequired]
 	public function parseTextFromFile(string $filePath): DataResponse {

lib/Controller/AssistantController.php

@@ -1,17 +1,19 @@
 <?php
 
-namespace OCA\TpAssistant\Controller;
+namespace OCA\Assistant\Controller;
 
-use OCA\TpAssistant\AppInfo\Application;
-use OCA\TpAssistant\Service\AssistantService;
+use OCA\Assistant\AppInfo\Application;
+use OCA\Assistant\Service\AssistantService;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\NoAdminRequired;
 use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\TemplateResponse;
 use OCP\AppFramework\Services\IInitialState;
 use OCP\IRequest;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class AssistantController extends Controller {
 
 	public function __construct(