Merge pull request #9945 from nextcloud/feat/document-ocs-apis

feat(ocs): document get api and amend return types
nextcloud · Aug 5, 2024 · 5280498 · 5280498
2 parents 01dba1a + 929873d
commit 5280498
Show file tree

Hide file tree

Showing 29 changed files with 156 additions and 18 deletions.
diff --git a/lib/Controller/AccountsController.php b/lib/Controller/AccountsController.php
@@ -28,13 +28,15 @@
 use OCA\Mail\Service\Sync\SyncService;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\JSONResponse;
 use OCP\IConfig;
 use OCP\IL10N;
 use OCP\IRequest;
 use OCP\Security\IRemoteHostValidator;
 use Psr\Log\LoggerInterface;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class AccountsController extends Controller {
 	private AccountService $accountService;
 	private string $currentUserId;

diff --git a/lib/Controller/AliasesController.php b/lib/Controller/AliasesController.php
@@ -15,9 +15,11 @@
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\JSONResponse;
 use OCP\IRequest;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class AliasesController extends Controller {
 	private AliasesService $aliasService;
 	private string $currentUserId;

diff --git a/lib/Controller/AutoCompleteController.php b/lib/Controller/AutoCompleteController.php
@@ -13,9 +13,11 @@
 use OCA\Mail\Http\TrapError;
 use OCA\Mail\Service\AutoCompletion\AutoCompleteService;
 use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\JSONResponse;
 use OCP\IRequest;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class AutoCompleteController extends Controller {
 	private AutoCompleteService $service;
 	private ?string $userId;

diff --git a/lib/Controller/AutoConfigController.php b/lib/Controller/AutoConfigController.php
@@ -18,11 +18,13 @@
 use OCA\Mail\Service\AutoConfig\MxRecord;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Attribute\UserRateLimit;
 use OCP\IRequest;
 use OCP\Security\IRemoteHostValidator;
 use function in_array;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class AutoConfigController extends Controller {
 	private IspDb $ispDb;
 	private MxRecord $mxRecord;

diff --git a/lib/Controller/AvatarsController.php b/lib/Controller/AvatarsController.php
@@ -14,10 +14,12 @@
 use OCA\Mail\Http\TrapError;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\JSONResponse;
 use OCP\AppFramework\Http\Response;
 use OCP\IRequest;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class AvatarsController extends Controller {
 	private IAvatarService $avatarService;
 	private string $uid;

diff --git a/lib/Controller/ContactIntegrationController.php b/lib/Controller/ContactIntegrationController.php
@@ -13,9 +13,11 @@
 use OCA\Mail\Service\ContactIntegration\ContactIntegrationService;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\JSONResponse;
 use OCP\IRequest;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class ContactIntegrationController extends Controller {
 	private ContactIntegrationService $service;
 

diff --git a/lib/Controller/DraftsController.php b/lib/Controller/DraftsController.php
@@ -19,9 +19,11 @@
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Utility\ITimeFactory;
 use OCP\IRequest;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class DraftsController extends Controller {
 	private DraftsService $service;
 	private string $userId;

diff --git a/lib/Controller/FollowUpController.php b/lib/Controller/FollowUpController.php
@@ -18,8 +18,10 @@
 use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\Attribute\NoAdminRequired;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\IRequest;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class FollowUpController extends Controller {
 
 	public function __construct(

diff --git a/lib/Controller/GoogleIntegrationController.php b/lib/Controller/GoogleIntegrationController.php
@@ -18,6 +18,7 @@
 use OCA\Mail\Service\AccountService;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Response;
 use OCP\AppFramework\Http\StandaloneTemplateResponse;
 use OCP\IRequest;
@@ -27,6 +28,7 @@
 
 use function filter_var;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class GoogleIntegrationController extends Controller {
 	private ?string $userId;
 	private GoogleIntegration $googleIntegration;

diff --git a/lib/Controller/ListController.php b/lib/Controller/ListController.php
@@ -18,10 +18,12 @@
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\Http\Client\IClientService;
 use OCP\IRequest;
 use Psr\Log\LoggerInterface;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class ListController extends Controller {
 	private IMailManager $mailManager;
 	private AccountService $accountService;

diff --git a/lib/Controller/LocalAttachmentsController.php b/lib/Controller/LocalAttachmentsController.php
@@ -15,9 +15,11 @@
 use OCA\Mail\Service\Attachment\UploadedFile;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\JSONResponse;
 use OCP\IRequest;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class LocalAttachmentsController extends Controller {
 	private IAttachmentService $attachmentService;
 	private string $userId;

diff --git a/lib/Controller/MailboxesController.php b/lib/Controller/MailboxesController.php
@@ -23,9 +23,11 @@
 use OCA\Mail\Service\Sync\SyncService;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\JSONResponse;
 use OCP\IRequest;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class MailboxesController extends Controller {
 	private AccountService $accountService;
 	private ?string $currentUserId;

diff --git a/lib/Controller/MessageApiController.php b/lib/Controller/MessageApiController.php
@@ -16,6 +16,7 @@
 use OCA\Mail\Http\TrapError;
 use OCA\Mail\IMAP\IMAPClientFactory;
 use OCA\Mail\Model\SmimeData;
+use OCA\Mail\ResponseDefinitions;
 use OCA\Mail\Service\AccountService;
 use OCA\Mail\Service\AliasesService;
 use OCA\Mail\Service\Attachment\AttachmentService;
@@ -41,6 +42,10 @@
 use function array_map;
 use function array_merge;
 
+/**
+ * @psalm-import-type MessageApiResponse from ResponseDefinitions
+ * @psalm-import-type MessageApiAttachment from ResponseDefinitions
+ */
 class MessageApiController extends OCSController {
 
 	private ?string $userId;
@@ -203,7 +208,13 @@ public function send(
 
 	/**
 	 * @param int $id
-	 * @return DataResponse
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_PARTIAL_CONTENT, MessageApiResponse, array{}>|DataResponse<Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, string, array{}>
+	 *
+	 * 200: Message found
+	 * 206: Message could not be decrypted, no "body" data returned
+	 * 404: User was not logged in
+	 * 404: Message, Account or Mailbox not found
+	 * 500: Could not connect to IMAP server
 	 */
 	#[BruteForceProtection('mailGetMessage')]
 	#[NoAdminRequired]
@@ -251,7 +262,7 @@ public function get(int $id): DataResponse {
 		$json = $imapMessage->getFullMessage($id, $loadBody);
 		$itineraries = $this->itineraryService->getCached($account, $mailbox, $message->getUid());
 		if ($itineraries) {
-			$json['itineraries'] = $itineraries;
+			$json['itineraries'] = $itineraries->jsonSerialize();
 		}
 		$json['attachments'] = array_map(function ($a) use ($id) {
 			return $this->enrichDownloadUrl(
@@ -268,7 +279,7 @@ public function get(int $id): DataResponse {
 			$smimeData->setIsSigned(true);
 			$smimeData->setSignatureIsValid($imapMessage->isSignatureValid());
 		}
-		$json['smime'] = $smimeData;
+		$json['smime'] = $smimeData->jsonSerialize();
 
 		$dkimResult = $this->dkimService->getCached($account, $mailbox, $message->getUid());
 		if (is_bool($dkimResult)) {
@@ -284,17 +295,30 @@ public function get(int $id): DataResponse {
 		return new DataResponse($json, Http::STATUS_OK);
 	}
 
+	/**
+	 * @param int $id the id of the message
+	 * @return DataResponse<Http::STATUS_OK|?string, array{}>|DataResponse<Http::STATUS_NOT_FOUND, string, array{}>
+	 *
+	 * 200: Message found
+	 * 404: User was not logged in
+	 * 404: Message, Account or Mailbox not found
+	 * 404: Could not find message on IMAP
+	 */
 	#[BruteForceProtection('mailGetRawMessage')]
 	#[NoAdminRequired]
 	#[NoCSRFRequired]
 	public function getRaw(int $id): DataResponse {
+		if ($this->userId === null) {
+			return new DataResponse('Account not found.', Http::STATUS_NOT_FOUND);
+		}
+
 		try {
 			$message = $this->mailManager->getMessage($this->userId, $id);
 			$mailbox = $this->mailManager->getMailbox($this->userId, $message->getMailboxId());
 			$account = $this->accountService->find($this->userId, $mailbox->getAccountId());
 		} catch (ClientException | DoesNotExistException $e) {
 			$this->logger->error('Message, Account or Mailbox not found', ['exception' => $e->getMessage()]);
-			return new DataResponse($e, Http::STATUS_FORBIDDEN);
+			return new DataResponse('Message, Account or Mailbox not found', Http::STATUS_NOT_FOUND);
 		}
 
 		$client = $this->clientFactory->getClient($account);
@@ -306,8 +330,8 @@ public function getRaw(int $id): DataResponse {
 				$message->getUid()
 			);
 		} catch (ServiceException $e) {
-			$this->logger->error('Message not found on IMAP or mail server went away', ['exception' => $e->getMessage()]);
-			return new DataResponse($e, Http::STATUS_NOT_FOUND);
+			$this->logger->error('Message not found on IMAP, or mail server went away', ['exception' => $e->getMessage()]);
+			return new DataResponse('Message not found', Http::STATUS_NOT_FOUND);
 		} finally {
 			$client->logout();
 		}
@@ -316,12 +340,12 @@ public function getRaw(int $id): DataResponse {
 	}
 
 	/**
-	 * @param int $id
+	 * @param int $id the id of the message
 	 * @param array $attachment
 	 *
 	 * @return array
 	 */
-	private function enrichDownloadUrl(int $id, array $attachment) {
+	private function enrichDownloadUrl(int $id, array $attachment): array {
 		$downloadUrl = $this->urlGenerator->linkToOCSRouteAbsolute('mail.messageApi.getAttachment',
 			[
 				'id' => $id,
@@ -331,17 +355,28 @@ private function enrichDownloadUrl(int $id, array $attachment) {
 		return $attachment;
 	}
 
+	/**
+	 * @param int $id
+	 * @param string $attachmentId
+	 * @return DataResponse<Http::STATUS_OK, MessageApiAttachment, array{}>|DataResponse<Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, string, array{}>
+	 *
+	 * 200: Message found
+	 * 404: User was not logged in
+	 * 404: Message, Account or Mailbox not found
+	 * 404: Could not find attachment
+	 * 500: Could not process attachment
+	 *
+	 */
 	#[NoCSRFRequired]
 	#[NoAdminRequired]
 	#[TrapError]
-	public function getAttachment(int $id,
-		string $attachmentId): DataResponse {
+	public function getAttachment(int $id, string $attachmentId): DataResponse {
 		try {
 			$message = $this->mailManager->getMessage($this->userId, $id);
 			$mailbox = $this->mailManager->getMailbox($this->userId, $message->getMailboxId());
 			$account = $this->accountService->find($this->userId, $mailbox->getAccountId());
 		} catch (DoesNotExistException | ClientException $e) {
-			return new DataResponse($e, Http::STATUS_FORBIDDEN);
+			return new DataResponse('Message, Account or Mailbox not found', Http::STATUS_NOT_FOUND);
 		}
 
 		try {
@@ -353,10 +388,10 @@ public function getAttachment(int $id,
 			);
 		} catch (\Horde_Imap_Client_Exception_NoSupportExtension | \Horde_Imap_Client_Exception | \Horde_Mime_Exception $e) {
 			$this->logger->error('Error when trying to process the attachment', ['exception' => $e]);
-			return new DataResponse($e, Http::STATUS_INTERNAL_SERVER_ERROR);
+			return new DataResponse('Error when trying to process the attachment', Http::STATUS_INTERNAL_SERVER_ERROR);
 		} catch (ServiceException | DoesNotExistException $e) {
 			$this->logger->error('Could not find attachment', ['exception' => $e]);
-			return new DataResponse($e, Http::STATUS_NOT_FOUND);
+			return new DataResponse('Could not find attachment', Http::STATUS_NOT_FOUND);
 		}
 
 		// Body party and embedded messages do not have a name

diff --git a/lib/Controller/MessagesController.php b/lib/Controller/MessagesController.php
@@ -35,6 +35,7 @@
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\ContentSecurityPolicy;
 use OCP\AppFramework\Http\JSONResponse;
 use OCP\AppFramework\Http\Response;
@@ -51,6 +52,7 @@
 use Psr\Log\LoggerInterface;
 use function array_map;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class MessagesController extends Controller {
 	private AccountService $accountService;
 	private IMailManager $mailManager;

diff --git a/lib/Controller/MicrosoftIntegrationController.php b/lib/Controller/MicrosoftIntegrationController.php
@@ -16,12 +16,14 @@
 use OCA\Mail\Service\AccountService;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\Response;
 use OCP\AppFramework\Http\StandaloneTemplateResponse;
 use OCP\IRequest;
 use Psr\Log\LoggerInterface;
 use function filter_var;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class MicrosoftIntegrationController extends Controller {
 	private ?string $userId;
 	private AccountService $accountService;

diff --git a/lib/Controller/OutOfOfficeController.php b/lib/Controller/OutOfOfficeController.php
@@ -19,11 +19,13 @@
 use OCA\Mail\Service\OutOfOfficeService;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\IRequest;
 use OCP\IUserSession;
 use OCP\User\IAvailabilityCoordinator;
 use Psr\Container\ContainerInterface;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class OutOfOfficeController extends Controller {
 	public function __construct(
 		IRequest $request,

diff --git a/lib/Controller/OutboxController.php b/lib/Controller/OutboxController.php
@@ -20,8 +20,10 @@
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\IRequest;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class OutboxController extends Controller {
 	private OutboxService $service;
 	private string $userId;

diff --git a/lib/Controller/PageController.php b/lib/Controller/PageController.php
@@ -23,6 +23,7 @@
 use OCA\Mail\Service\SmimeService;
 use OCA\Viewer\Event\LoadViewer;
 use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\ContentSecurityPolicy;
 use OCP\AppFramework\Http\RedirectResponse;
 use OCP\AppFramework\Http\TemplateResponse;
@@ -48,6 +49,7 @@
 use function http_build_query;
 use function json_decode;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class PageController extends Controller {
 	private IURLGenerator $urlGenerator;
 	private IConfig $config;

diff --git a/lib/Controller/PreferencesController.php b/lib/Controller/PreferencesController.php
@@ -13,9 +13,11 @@
 use OCA\Mail\Exception\ClientException;
 use OCA\Mail\Http\TrapError;
 use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
 use OCP\AppFramework\Http\JSONResponse;
 use OCP\IRequest;
 
+#[OpenAPI(scope: OpenAPI::SCOPE_IGNORE)]
 class PreferencesController extends Controller {
 	private IUserPreferences $userPreference;
 	private string $userId;