user_status: Add OpenAPI spec

apps/user_status/lib/Controller/HeartbeatController.php

@@ -6,6 +6,7 @@
  * @copyright Copyright (c) 2020, Georg Ehrke
  *
  * @author Georg Ehrke <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -23,12 +24,12 @@
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  *
  */
+
 namespace OCA\UserStatus\Controller;
 
 use OCA\UserStatus\Db\UserStatus;
+use OCA\UserStatus\ResponseDefinitions;
 use OCA\UserStatus\Service\StatusService;
-use OCP\AppFramework\Controller;
-use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
@@ -53,12 +54,13 @@ class HeartbeatController extends OCSController {
 	/** @var StatusService */
 	private $service;
 
-	public function __construct(string $appName,
-								IRequest $request,
-								IEventDispatcher $eventDispatcher,
-								IUserSession $userSession,
-								ITimeFactory $timeFactory,
-								StatusService $service) {
+	public function __construct(
+		string $appName,
+		IRequest $request,
+		IEventDispatcher $eventDispatcher,
+		IUserSession $userSession,
+		ITimeFactory $timeFactory,
+		StatusService $service) {
 		parent::__construct($appName, $request);
 		$this->eventDispatcher = $eventDispatcher;
 		$this->userSession = $userSession;
@@ -69,11 +71,14 @@ public function __construct(string $appName,
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param string $status
-	 * @return DataResponse
+	 * @param string $status online, away
+	 * @psalm-import-type PrivateUserStatus from ResponseDefinitions
+	 * @return DataResponse<PrivateUserStatus> 200 Status successfully updated
+	 * @return DataResponse 204 User has no status to update
+	 * @return DataResponse 400 Invalid status to update
 	 */
 	public function heartbeat(string $status): DataResponse {
-		if (!\in_array($status, [IUserStatus::ONLINE, IUserStatus::AWAY], true)) {
+		if (!in_array($status, [IUserStatus::ONLINE, IUserStatus::AWAY], true)) {
 			return new DataResponse([], Http::STATUS_BAD_REQUEST);
 		}
 

apps/user_status/lib/Controller/PredefinedStatusController.php

@@ -6,6 +6,7 @@
  * @copyright Copyright (c) 2020, Georg Ehrke
  *
  * @author Georg Ehrke <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -23,8 +24,10 @@
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  *
  */
+
 namespace OCA\UserStatus\Controller;
 
+use OCA\UserStatus\ResponseDefinitions;
 use OCA\UserStatus\Service\PredefinedStatusService;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
@@ -47,19 +50,21 @@ class PredefinedStatusController extends OCSController {
 	 * @param IRequest $request
 	 * @param PredefinedStatusService $predefinedStatusService
 	 */
-	public function __construct(string $appName,
-								IRequest $request,
-								PredefinedStatusService $predefinedStatusService) {
+	public function __construct(
+		string $appName,
+		IRequest $request,
+		PredefinedStatusService $predefinedStatusService) {
 		parent::__construct($appName, $request);
 		$this->predefinedStatusService = $predefinedStatusService;
 	}
 
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @return DataResponse
+	 * @psalm-import-type PredefinedStatus from ResponseDefinitions
+	 * @return DataResponse<PredefinedStatus[]> 200
 	 */
-	public function findAll():DataResponse {
+	public function findAll(): DataResponse {
 		// Filtering out the invisible one, that should only be set by API
 		return new DataResponse(array_filter($this->predefinedStatusService->getDefaultStatuses(), function (array $status) {
 			return !array_key_exists('visible', $status) || $status['visible'] === true;

apps/user_status/lib/Controller/StatusesController.php

@@ -7,6 +7,7 @@
  *
  * @author Christoph Wurst <[email protected]>
  * @author Georg Ehrke <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -24,9 +25,11 @@
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  *
  */
+
 namespace OCA\UserStatus\Controller;
 
 use OCA\UserStatus\Db\UserStatus;
+use OCA\UserStatus\ResponseDefinitions;
 use OCA\UserStatus\Service\StatusService;
 use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Http\DataResponse;
@@ -47,9 +50,10 @@ class StatusesController extends OCSController {
 	 * @param IRequest $request
 	 * @param StatusService $service
 	 */
-	public function __construct(string $appName,
-								IRequest $request,
-								StatusService $service) {
+	public function __construct(
+		string $appName,
+		IRequest $request,
+		StatusService $service) {
 		parent::__construct($appName, $request);
 		$this->service = $service;
 	}
@@ -59,7 +63,8 @@ public function __construct(string $appName,
 	 *
 	 * @param int|null $limit
 	 * @param int|null $offset
-	 * @return DataResponse
+	 * @psalm-import-type PublicUserStatus from ResponseDefinitions
+	 * @return DataResponse<PublicUserStatus[]> 200
 	 */
 	public function findAll(?int $limit = null, ?int $offset = null): DataResponse {
 		$allStatuses = $this->service->findAll($limit, $offset);
@@ -73,7 +78,8 @@ public function findAll(?int $limit = null, ?int $offset = null): DataResponse {
 	 * @NoAdminRequired
 	 *
 	 * @param string $userId
-	 * @return DataResponse
+	 * @psalm-import-type PublicUserStatus from ResponseDefinitions
+	 * @return DataResponse<PublicUserStatus> 200
 	 * @throws OCSNotFoundException
 	 */
 	public function find(string $userId): DataResponse {
@@ -88,7 +94,7 @@ public function find(string $userId): DataResponse {
 
 	/**
 	 * @param UserStatus $status
-	 * @return array{userId: string, message: string, icon: string, clearAt: int, status: string}
+	 * @return array
 	 */
 	private function formatStatus(UserStatus $status): array {
 		$visibleStatus = $status->getStatus();

apps/user_status/lib/Controller/UserStatusController.php

@@ -8,6 +8,7 @@
  * @author Georg Ehrke <[email protected]>
  * @author Joas Schilling <[email protected]>
  * @author Simon Spannagel <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -25,6 +26,7 @@
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  *
  */
+
 namespace OCA\UserStatus\Controller;
 
 use OCA\UserStatus\Db\UserStatus;
@@ -33,6 +35,7 @@
 use OCA\UserStatus\Exception\InvalidStatusIconException;
 use OCA\UserStatus\Exception\InvalidStatusTypeException;
 use OCA\UserStatus\Exception\StatusMessageTooLongException;
+use OCA\UserStatus\ResponseDefinitions;
 use OCA\UserStatus\Service\StatusService;
 use OCP\AppFramework\Db\DoesNotExistException;
 use OCP\AppFramework\Http\DataResponse;
@@ -59,14 +62,15 @@ class UserStatusController extends OCSController {
 	 * @param string $appName
 	 * @param IRequest $request
 	 * @param string $userId
-	 * @param ILogger $logger;
+	 * @param ILogger $logger
 	 * @param StatusService $service
 	 */
-	public function __construct(string $appName,
-								IRequest $request,
-								string $userId,
-								ILogger $logger,
-								StatusService $service) {
+	public function __construct(
+		string $appName,
+		IRequest $request,
+		string $userId,
+		ILogger $logger,
+		StatusService $service) {
 		parent::__construct($appName, $request);
 		$this->userId = $userId;
 		$this->logger = $logger;
@@ -76,7 +80,8 @@ public function __construct(string $appName,
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @return DataResponse
+	 * @psalm-import-type PrivateUserStatus from ResponseDefinitions
+	 * @return DataResponse<PrivateUserStatus> 200
 	 * @throws OCSNotFoundException
 	 */
 	public function getStatus(): DataResponse {
@@ -93,7 +98,8 @@ public function getStatus(): DataResponse {
 	 * @NoAdminRequired
 	 *
 	 * @param string $statusType
-	 * @return DataResponse
+	 * @psalm-import-type PrivateUserStatus from ResponseDefinitions
+	 * @return DataResponse<PrivateUserStatus> 200
 	 * @throws OCSBadRequestException
 	 */
 	public function setStatus(string $statusType): DataResponse {
@@ -113,11 +119,11 @@ public function setStatus(string $statusType): DataResponse {
 	 *
 	 * @param string $messageId
 	 * @param int|null $clearAt
-	 * @return DataResponse
+	 * @psalm-import-type PrivateUserStatus from ResponseDefinitions
+	 * @return DataResponse<PrivateUserStatus> 200
 	 * @throws OCSBadRequestException
 	 */
-	public function setPredefinedMessage(string $messageId,
-										 ?int $clearAt): DataResponse {
+	public function setPredefinedMessage(string $messageId, ?int $clearAt): DataResponse {
 		try {
 			$status = $this->service->setPredefinedMessage($this->userId, $messageId, $clearAt);
 			$this->service->removeBackupUserStatus($this->userId);
@@ -137,12 +143,13 @@ public function setPredefinedMessage(string $messageId,
 	 * @param string|null $statusIcon
 	 * @param string|null $message
 	 * @param int|null $clearAt
-	 * @return DataResponse
+	 * @psalm-import-type PrivateUserStatus from ResponseDefinitions
+	 * @return DataResponse<PrivateUserStatus> 200
 	 * @throws OCSBadRequestException
 	 */
 	public function setCustomMessage(?string $statusIcon,
-									 ?string $message,
-									 ?int $clearAt): DataResponse {
+		?string $message,
+		?int $clearAt): DataResponse {
 		try {
 			if (($message !== null && $message !== '') || ($clearAt !== null && $clearAt !== 0)) {
 				$status = $this->service->setCustomMessage($this->userId, $statusIcon, $message, $clearAt);
@@ -167,7 +174,7 @@ public function setCustomMessage(?string $statusIcon,
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @return DataResponse
+	 * @return DataResponse 200
 	 */
 	public function clearStatus(): DataResponse {
 		$this->service->clearStatus($this->userId);
@@ -177,7 +184,7 @@ public function clearStatus(): DataResponse {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @return DataResponse
+	 * @return DataResponse 200
 	 */
 	public function clearMessage(): DataResponse {
 		$this->service->clearMessage($this->userId);

apps/user_status/lib/ResponseDefinitions.php

@@ -0,0 +1,57 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Kate Döen <[email protected]>
+ *
+ * @author Kate Döen <[email protected]>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCA\UserStatus;
+
+/**
+ * @psalm-type ClearAt = array{
+ *     type: string,
+ *     time: string|int,
+ * }
+ *
+ * @psalm-type PredefinedStatus = array{
+ *     id: string,
+ *     icon: string,
+ *     message: string,
+ *     clearAt: ClearAt|null,
+ *     visible: bool|null,
+ * }
+ *
+ * @psalm-type PublicUserStatus = array{
+ *     userId: string,
+ *     message: string|null,
+ *     icon: string|null,
+ *     clearAt: int|ClearAt|null,
+ *     status: string,
+ * }
+ *
+ * @psalm-type PrivateUserStatus = PublicUserStatus&array{
+ *     messageId: string|null,
+ *     messageIsPredefined: bool,
+ *     statusIsUserDefined: bool,
+ * }
+ */
+class ResponseDefinitions {
+}