core: Add OpenAPI spec

Signed-off-by: jld3103 <jld3103yt@gmail.com>

31 files changed, 450 insertions, 68 deletions

diff --git a/core/Controller/AppPasswordController.php b/core/Controller/AppPasswordController.php
index 90020330ea1..096261d2311 100644
--- a/core/Controller/AppPasswordController.php
+++ b/core/Controller/AppPasswordController.php
@@ -8,6 +8,7 @@ declare(strict_types=1);
  * @author Christoph Wurst <christoph@winzerhof-wurst.at>
  * @author Daniel Kesselberg <mail@danielkesselberg.de>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -31,6 +32,7 @@ use OC\Authentication\Events\AppPasswordCreatedEvent;
 use OC\Authentication\Exceptions\InvalidTokenException;
 use OC\Authentication\Token\IProvider;
 use OC\Authentication\Token\IToken;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCS\OCSForbiddenException;
 use OCP\Authentication\Exceptions\CredentialsUnavailableException;
@@ -57,7 +59,12 @@ class AppPasswordController extends \OCP\AppFramework\OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @throws OCSForbiddenException
+	 * Create app password
+	 *
+	 * @return DataResponse<Http::STATUS_OK, array{apppassword: string}, array{}>
+	 * @throws OCSForbiddenException Creating app password is not allowed
+	 *
+	 * 200: App password returned
 	 */
 	public function getAppPassword(): DataResponse {
 		// We do not allow the creation of new tokens if this is an app password
@@ -102,6 +109,13 @@ class AppPasswordController extends \OCP\AppFramework\OCSController {
 
 	/**
 	 * @NoAdminRequired
+	 *
+	 * Delete app password
+	 *
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @throws OCSForbiddenException Deleting app password is not allowed
+	 *
+	 * 200: App password deleted successfully
 	 */
 	public function deleteAppPassword(): DataResponse {
 		if (!$this->session->exists('app_password')) {
@@ -122,6 +136,13 @@ class AppPasswordController extends \OCP\AppFramework\OCSController {
 
 	/**
 	 * @NoAdminRequired
+	 *
+	 * Rotate app password
+	 *
+	 * @return DataResponse<Http::STATUS_OK, array{apppassword: string}, array{}>
+	 * @throws OCSForbiddenException Rotating app password is not allowed
+	 *
+	 * 200: App password returned
 	 */
 	public function rotateAppPassword(): DataResponse {
 		if (!$this->session->exists('app_password')) {
diff --git a/core/Controller/AutoCompleteController.php b/core/Controller/AutoCompleteController.php
index 29a0788ad57..15b78e53dc0 100644
--- a/core/Controller/AutoCompleteController.php
+++ b/core/Controller/AutoCompleteController.php
@@ -30,6 +30,8 @@ declare(strict_types=1);
  */
 namespace OC\Core\Controller;
 
+use OCA\Core\ResponseDefinitions;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
 use OCP\Collaboration\AutoComplete\AutoCompleteEvent;
@@ -39,6 +41,9 @@ use OCP\EventDispatcher\IEventDispatcher;
 use OCP\IRequest;
 use OCP\Share\IShare;
 
+/**
+ * @psalm-import-type CoreAutocompleteResult from ResponseDefinitions
+ */
 class AutoCompleteController extends OCSController {
 	public function __construct(
 		string $appName,
@@ -52,7 +57,17 @@ class AutoCompleteController extends OCSController {
 
 	/**
 	 * @NoAdminRequired
+	 *
+	 * Autocomplete a query
+	 *
+	 * @param string $search Text to search for
+	 * @param string|null $itemType Type of the items to search for
+	 * @param string|null $itemId ID of the items to search for
 	 * @param string|null $sorter can be piped, top prio first, e.g.: "commenters|share-recipients"
+	 * @param int[] $shareTypes Types of shares to search for
+	 * @param int $limit Maximum number of results to return
+	 *
+	 * @return DataResponse<Http::STATUS_OK, CoreAutocompleteResult[], array{}>
 	 */
 	public function get(string $search, ?string $itemType, ?string $itemId, ?string $sorter = null, array $shareTypes = [IShare::TYPE_USER], int $limit = 10): DataResponse {
 		// if enumeration/user listings are disabled, we'll receive an empty
@@ -89,18 +104,37 @@ class AutoCompleteController extends OCSController {
 		return new DataResponse($results);
 	}
 
+	/**
+	 * @return CoreAutocompleteResult[]
+	 */
 	protected function prepareResultArray(array $results): array {
 		$output = [];
+		/** @var string $type */
 		foreach ($results as $type => $subResult) {
 			foreach ($subResult as $result) {
+				/** @var ?string $icon */
+				$icon = array_key_exists('icon', $result) ? $result['icon'] : null;
+
+				/** @var string $label */
+				$label = $result['label'];
+
+				/** @var ?string $subline */
+				$subline = array_key_exists('subline', $result) ? $result['subline'] : null;
+
+				/** @var ?string $status */
+				$status = array_key_exists('status', $result) && is_string($result['status']) ? $result['status'] : null;
+
+				/** @var ?string $shareWithDisplayNameUnique */
+				$shareWithDisplayNameUnique = array_key_exists('shareWithDisplayNameUnique', $result) ? $result['shareWithDisplayNameUnique'] : null;
+
 				$output[] = [
 					'id' => (string) $result['value']['shareWith'],
-					'label' => $result['label'],
-					'icon' => $result['icon'] ?? '',
+					'label' => $label,
+					'icon' => $icon ?? '',
 					'source' => $type,
-					'status' => $result['status'] ?? '',
-					'subline' => $result['subline'] ?? '',
-					'shareWithDisplayNameUnique' => $result['shareWithDisplayNameUnique'] ?? '',
+					'status' => $status ?? '',
+					'subline' => $subline ?? '',
+					'shareWithDisplayNameUnique' => $shareWithDisplayNameUnique ?? '',
 				];
 			}
 		}
diff --git a/core/Controller/AvatarController.php b/core/Controller/AvatarController.php
index ba1792af708..32858b52612 100644
--- a/core/Controller/AvatarController.php
+++ b/core/Controller/AvatarController.php
@@ -12,6 +12,7 @@
  * @author Roeland Jago Douma <roeland@famdouma.nl>
  * @author Thomas Müller <thomas.mueller@tmit.eu>
  * @author Vincent Petry <vincent@nextcloud.com>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license AGPL-3.0
  *
@@ -72,7 +73,14 @@ class AvatarController extends Controller {
 	 * @NoSameSiteCookieRequired
 	 * @PublicPage
 	 *
-	 * @return JSONResponse|FileDisplayResponse
+	 * Get the dark avatar
+	 *
+	 * @param string $userId ID of the user
+	 * @param int $size Size of the avatar
+	 * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string, X-NC-IsCustomAvatar: int}>|JSONResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 *
+	 * 200: Avatar returned
+	 * 404: Avatar not found
 	 */
 	public function getAvatarDark(string $userId, int $size) {
 		if ($size <= 64) {
@@ -111,7 +119,14 @@ class AvatarController extends Controller {
 	 * @NoSameSiteCookieRequired
 	 * @PublicPage
 	 *
-	 * @return JSONResponse|FileDisplayResponse
+	 * Get the avatar
+	 *
+	 * @param string $userId ID of the user
+	 * @param int $size Size of the avatar
+	 * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string, X-NC-IsCustomAvatar: int}>|JSONResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 *
+	 * 200: Avatar returned
+	 * 404: Avatar not found
 	 */
 	public function getAvatar(string $userId, int $size) {
 		if ($size <= 64) {
diff --git a/core/Controller/CSRFTokenController.php b/core/Controller/CSRFTokenController.php
index 95e67371b5d..fb51744fb74 100644
--- a/core/Controller/CSRFTokenController.php
+++ b/core/Controller/CSRFTokenController.php
@@ -7,6 +7,7 @@ declare(strict_types=1);
  *
  * @author Christoph Wurst <christoph@winzerhof-wurst.at>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -29,9 +30,11 @@ namespace OC\Core\Controller;
 use OC\Security\CSRF\CsrfTokenManager;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\JSONResponse;
 use OCP\IRequest;
 
+#[IgnoreOpenAPI]
 class CSRFTokenController extends Controller {
 	public function __construct(
 		string $appName,
diff --git a/core/Controller/ClientFlowLoginController.php b/core/Controller/ClientFlowLoginController.php
index 082d5b3f92e..3f92ad8cf30 100644
--- a/core/Controller/ClientFlowLoginController.php
+++ b/core/Controller/ClientFlowLoginController.php
@@ -12,6 +12,7 @@
  * @author Roeland Jago Douma <roeland@famdouma.nl>
  * @author RussellAult <RussellAult@users.noreply.github.com>
  * @author Sergej Nikolaev <kinolaev@gmail.com>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -41,6 +42,7 @@ use OCA\OAuth2\Db\AccessTokenMapper;
 use OCA\OAuth2\Db\ClientMapper;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\Attribute\UseSession;
 use OCP\AppFramework\Http\Response;
 use OCP\AppFramework\Http\StandaloneTemplateResponse;
@@ -56,6 +58,7 @@ use OCP\Security\ICrypto;
 use OCP\Security\ISecureRandom;
 use OCP\Session\Exceptions\SessionNotAvailableException;
 
+#[IgnoreOpenAPI]
 class ClientFlowLoginController extends Controller {
 	public const STATE_NAME = 'client.flow.state.token';
 
diff --git a/core/Controller/ClientFlowLoginV2Controller.php b/core/Controller/ClientFlowLoginV2Controller.php
index 8a21148f589..b03f961742e 100644
--- a/core/Controller/ClientFlowLoginV2Controller.php
+++ b/core/Controller/ClientFlowLoginV2Controller.php
@@ -31,8 +31,10 @@ use OC\Authentication\Exceptions\InvalidTokenException;
 use OC\Core\Db\LoginFlowV2;
 use OC\Core\Exception\LoginFlowV2NotFoundException;
 use OC\Core\Service\LoginFlowV2Service;
+use OCA\Core\ResponseDefinitions;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\Attribute\UseSession;
 use OCP\AppFramework\Http\JSONResponse;
 use OCP\AppFramework\Http\RedirectResponse;
@@ -47,6 +49,10 @@ use OCP\IUser;
 use OCP\IUserSession;
 use OCP\Security\ISecureRandom;
 
+/**
+ * @psalm-import-type CoreLoginFlowV2Credentials from ResponseDefinitions
+ * @psalm-import-type CoreLoginFlowV2 from ResponseDefinitions
+ */
 class ClientFlowLoginV2Controller extends Controller {
 	public const TOKEN_NAME = 'client.flow.v2.login.token';
 	public const STATE_NAME = 'client.flow.v2.state.token';
@@ -69,6 +75,14 @@ class ClientFlowLoginV2Controller extends Controller {
 	/**
 	 * @NoCSRFRequired
 	 * @PublicPage
+	 *
+	 * Poll the login flow credentials
+	 *
+	 * @param string $token Token of the flow
+	 * @return JSONResponse<Http::STATUS_OK, CoreLoginFlowV2Credentials, array{}>|JSONResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 *
+	 * 200: Login flow credentials returned
+	 * 404: Login flow not found or completed
 	 */
 	public function poll(string $token): JSONResponse {
 		try {
@@ -77,13 +91,14 @@ class ClientFlowLoginV2Controller extends Controller {
 			return new JSONResponse([], Http::STATUS_NOT_FOUND);
 		}
 
-		return new JSONResponse($creds);
+		return new JSONResponse($creds->jsonSerialize());
 	}
 
 	/**
 	 * @NoCSRFRequired
 	 * @PublicPage
 	 */
+	#[IgnoreOpenAPI]
 	#[UseSession]
 	public function landing(string $token, $user = ''): Response {
 		if (!$this->loginFlowV2Service->startLoginFlow($token)) {
@@ -101,6 +116,7 @@ class ClientFlowLoginV2Controller extends Controller {
 	 * @NoCSRFRequired
 	 * @PublicPage
 	 */
+	#[IgnoreOpenAPI]
 	#[UseSession]
 	public function showAuthPickerPage($user = ''): StandaloneTemplateResponse {
 		try {
@@ -134,6 +150,7 @@ class ClientFlowLoginV2Controller extends Controller {
 	 * @NoCSRFRequired
 	 * @NoSameSiteCookieRequired
 	 */
+	#[IgnoreOpenAPI]
 	#[UseSession]
 	public function grantPage(?string $stateToken): StandaloneTemplateResponse {
 		if ($stateToken === null) {
@@ -267,6 +284,10 @@ class ClientFlowLoginV2Controller extends Controller {
 	/**
 	 * @NoCSRFRequired
 	 * @PublicPage
+	 *
+	 * Init a login flow
+	 *
+	 * @return JSONResponse<Http::STATUS_OK, CoreLoginFlowV2, array{}>
 	 */
 	public function init(): JSONResponse {
 		// Get client user agent
diff --git a/core/Controller/CollaborationResourcesController.php b/core/Controller/CollaborationResourcesController.php
index da90f27c9ef..832b4207e6f 100644
--- a/core/Controller/CollaborationResourcesController.php
+++ b/core/Controller/CollaborationResourcesController.php
@@ -8,6 +8,7 @@ declare(strict_types=1);
  * @author Joas Schilling <coding@schilljs.com>
  * @author Julius Härtl <jus@bitgrid.net>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -29,6 +30,7 @@ declare(strict_types=1);
 namespace OC\Core\Controller;
 
 use Exception;
+use OCA\Core\ResponseDefinitions;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
@@ -41,6 +43,10 @@ use OCP\IRequest;
 use OCP\IUserSession;
 use Psr\Log\LoggerInterface;
 
+/**
+ * @psalm-import-type CoreOpenGraphObject from ResponseDefinitions
+ * @psalm-import-type CoreCollection from ResponseDefinitions
+ */
 class CollaborationResourcesController extends OCSController {
 	public function __construct(
 		string $appName,
@@ -70,8 +76,13 @@ class CollaborationResourcesController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param int $collectionId
-	 * @return DataResponse
+	 * Get a collection
+	 *
+	 * @param int $collectionId ID of the collection
+	 * @return DataResponse<Http::STATUS_OK, CoreCollection, array{}>|DataResponse<Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, array<empty>, array{}>
+	 *
+	 * 200: Collection returned
+	 * 404: Collection not found
 	 */
 	public function listCollection(int $collectionId): DataResponse {
 		try {
@@ -86,8 +97,13 @@ class CollaborationResourcesController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param string $filter
-	 * @return DataResponse
+	 * Search for collections
+	 *
+	 * @param string $filter Filter collections
+	 * @return DataResponse<Http::STATUS_OK, CoreCollection[], array{}>|DataResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 *
+	 * 200: Collections returned
+	 * 404: Collection not found
 	 */
 	public function searchCollections(string $filter): DataResponse {
 		try {
@@ -102,10 +118,15 @@ class CollaborationResourcesController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param int $collectionId
-	 * @param string $resourceType
-	 * @param string $resourceId
-	 * @return DataResponse
+	 * Add a resource to a collection
+	 *
+	 * @param int $collectionId ID of the collection
+	 * @param string $resourceType Name of the resource
+	 * @param string $resourceId ID of the resource
+	 * @return DataResponse<Http::STATUS_OK, CoreCollection, array{}>|DataResponse<Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, array<empty>, array{}>
+	 *
+	 * 200: Collection returned
+	 * 404: Collection not found or resource inaccessible
 	 */
 	public function addResource(int $collectionId, string $resourceType, string $resourceId): DataResponse {
 		try {
@@ -131,10 +152,15 @@ class CollaborationResourcesController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param int $collectionId
-	 * @param string $resourceType
-	 * @param string $resourceId
-	 * @return DataResponse
+	 * Remove a resource from a collection
+	 *
+	 * @param int $collectionId ID of the collection
+	 * @param string $resourceType Name of the resource
+	 * @param string $resourceId ID of the resource
+	 * @return DataResponse<Http::STATUS_OK, CoreCollection, array{}>|DataResponse<Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, array<empty>, array{}>
+	 *
+	 * 200: Collection returned
+	 * 404: Collection or resource not found
 	 */
 	public function removeResource(int $collectionId, string $resourceType, string $resourceId): DataResponse {
 		try {
@@ -157,9 +183,14 @@ class CollaborationResourcesController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param string $resourceType
-	 * @param string $resourceId
-	 * @return DataResponse
+	 * Get collections by resource
+	 *
+	 * @param string $resourceType Type of the resource
+	 * @param string $resourceId ID of the resource
+	 * @return DataResponse<Http::STATUS_OK, CoreCollection[], array{}>|DataResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 *
+	 * 200: Collections returned
+	 * 404: Resource not accessible
 	 */
 	public function getCollectionsByResource(string $resourceType, string $resourceId): DataResponse {
 		try {
@@ -178,10 +209,16 @@ class CollaborationResourcesController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param string $baseResourceType
-	 * @param string $baseResourceId
-	 * @param string $name
-	 * @return DataResponse
+	 * Create a collection for a resource
+	 *
+	 * @param string $baseResourceType Type of the base resource
+	 * @param string $baseResourceId ID of the base resource
+	 * @param string $name Name of the collection
+	 * @return DataResponse<Http::STATUS_OK, CoreCollection, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, array<empty>, array{}>
+	 *
+	 * 200: Collection returned
+	 * 400: Creating collection is not possible
+	 * 404: Resource inaccessible
 	 */
 	public function createCollectionOnResource(string $baseResourceType, string $baseResourceId, string $name): DataResponse {
 		if (!isset($name[0]) || isset($name[64])) {
@@ -207,9 +244,14 @@ class CollaborationResourcesController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param int $collectionId
-	 * @param string $collectionName
-	 * @return DataResponse
+	 * Rename a collection
+	 *
+	 * @param int $collectionId ID of the collection
+	 * @param string $collectionName New name
+	 * @return DataResponse<Http::STATUS_OK, CoreCollection, array{}>|DataResponse<Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, array<empty>, array{}>
+	 *
+	 * 200: Collection returned
+	 * 404: Collection not found
 	 */
 	public function renameCollection(int $collectionId, string $collectionName): DataResponse {
 		try {
@@ -223,6 +265,9 @@ class CollaborationResourcesController extends OCSController {
 		return $this->respondCollection($collection);
 	}
 
+	/**
+	 * @return DataResponse<Http::STATUS_OK, CoreCollection, array{}>|DataResponse<Http::STATUS_NOT_FOUND|Http::STATUS_INTERNAL_SERVER_ERROR, array<empty>, array{}>
+	 */
 	protected function respondCollection(ICollection $collection): DataResponse {
 		try {
 			return new DataResponse($this->prepareCollection($collection));
@@ -234,6 +279,9 @@ class CollaborationResourcesController extends OCSController {
 		}
 	}
 
+	/**
+	 * @return CoreCollection[]
+	 */
 	protected function prepareCollections(array $collections): array {
 		$result = [];
 
@@ -249,6 +297,9 @@ class CollaborationResourcesController extends OCSController {
 		return $result;
 	}
 
+	/**
+	 * @return CoreCollection
+	 */
 	protected function prepareCollection(ICollection $collection): array {
 		if (!$collection->canAccess($this->userSession->getUser())) {
 			throw new CollectionException('Can not access collection');
@@ -261,7 +312,10 @@ class CollaborationResourcesController extends OCSController {
 		];
 	}
 
-	protected function prepareResources(array $resources): ?array {
+	/**
+	 * @return CoreOpenGraphObject[]
+	 */
+	protected function prepareResources(array $resources): array {
 		$result = [];
 
 		foreach ($resources as $resource) {
@@ -276,6 +330,9 @@ class CollaborationResourcesController extends OCSController {
 		return $result;
 	}
 
+	/**
+	 * @return CoreOpenGraphObject
+	 */
 	protected function prepareResource(IResource $resource): array {
 		if (!$resource->canAccess($this->userSession->getUser())) {
 			throw new ResourceException('Can not access resource');
diff --git a/core/Controller/CssController.php b/core/Controller/CssController.php
index 7aec5850aea..30e0b0ce73b 100644
--- a/core/Controller/CssController.php
+++ b/core/Controller/CssController.php
@@ -11,6 +11,7 @@ declare(strict_types=1);
  * @author Morris Jobke <hey@morrisjobke.de>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
  * @author Thomas Citharel <nextcloud@tcit.fr>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -33,6 +34,7 @@ namespace OC\Core\Controller;
 use OC\Files\AppData\Factory;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\FileDisplayResponse;
 use OCP\AppFramework\Http\NotFoundResponse;
 use OCP\AppFramework\Http\Response;
@@ -43,6 +45,7 @@ use OCP\Files\SimpleFS\ISimpleFile;
 use OCP\Files\SimpleFS\ISimpleFolder;
 use OCP\IRequest;
 
+#[IgnoreOpenAPI]
 class CssController extends Controller {
 	protected IAppData $appData;
 
diff --git a/core/Controller/ErrorController.php b/core/Controller/ErrorController.php
index 550b320a989..9882b481951 100644
--- a/core/Controller/ErrorController.php
+++ b/core/Controller/ErrorController.php
@@ -6,6 +6,7 @@ declare(strict_types=1);
  * @copyright Copyright (c) 2022 Julius Härtl <jus@bitgrid.net>
  *
  * @author Julius Härtl <jus@bitgrid.net>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -27,8 +28,10 @@ declare(strict_types=1);
 namespace OC\Core\Controller;
 
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\TemplateResponse;
 
+#[IgnoreOpenAPI]
 class ErrorController extends \OCP\AppFramework\Controller {
 	/**
 	 * @PublicPage
diff --git a/core/Controller/GuestAvatarController.php b/core/Controller/GuestAvatarController.php
index 6f06451b796..3270a1f7f5a 100644
--- a/core/Controller/GuestAvatarController.php
+++ b/core/Controller/GuestAvatarController.php
@@ -3,6 +3,7 @@
  * @copyright Copyright (c) 2019, Michael Weimann <mail@michael-weimann.eu>
  *
  * @author Michael Weimann <mail@michael-weimann.eu>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -25,6 +26,7 @@ namespace OC\Core\Controller;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\FileDisplayResponse;
+use OCP\AppFramework\Http\Response;
 use OCP\IAvatarManager;
 use OCP\IRequest;
 use Psr\Log\LoggerInterface;
@@ -46,14 +48,18 @@ class GuestAvatarController extends Controller {
 	}
 
 	/**
-	 * Returns a guest avatar image response.
+	 * Returns a guest avatar image response
 	 *
 	 * @PublicPage
 	 * @NoCSRFRequired
 	 *
 	 * @param string $guestName The guest name, e.g. "Albert"
 	 * @param string $size The desired avatar size, e.g. 64 for 64x64px
-	 * @return FileDisplayResponse|Http\Response
+	 * @param bool|null $darkTheme Return dark avatar
+	 * @return FileDisplayResponse<Http::STATUS_OK|Http::STATUS_CREATED, array{Content-Type: string}>|Response<Http::STATUS_INTERNAL_SERVER_ERROR, array{}>
+	 *
+	 * 200: Custom avatar returned
+	 * 201: Avatar returned
 	 */
 	public function getAvatar(string $guestName, string $size, ?bool $darkTheme = false) {
 		$size = (int) $size;
@@ -95,8 +101,17 @@ class GuestAvatarController extends Controller {
 	}
 
 	/**
+	 * Returns a dark guest avatar image response
+	 *
 	 * @PublicPage
 	 * @NoCSRFRequired
+	 *
+	 * @param string $guestName The guest name, e.g. "Albert"
+	 * @param string $size The desired avatar size, e.g. 64 for 64x64px
+	 * @return FileDisplayResponse<Http::STATUS_OK|Http::STATUS_CREATED, array{Content-Type: string}>|Response<Http::STATUS_INTERNAL_SERVER_ERROR, array{}>
+	 *
+	 * 200: Custom avatar returned
+	 * 201: Avatar returned
 	 */
 	public function getAvatarDark(string $guestName, string $size) {
 		return $this->getAvatar($guestName, $size, true);
diff --git a/core/Controller/HoverCardController.php b/core/Controller/HoverCardController.php
index cfe95be0431..9a76ee4a09a 100644
--- a/core/Controller/HoverCardController.php
+++ b/core/Controller/HoverCardController.php
@@ -5,6 +5,7 @@ declare(strict_types=1);
  * @copyright 2021 Joas Schilling <coding@schilljs.com>
  *
  * @author Joas Schilling <coding@schilljs.com>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -25,13 +26,16 @@ declare(strict_types=1);
 namespace OC\Core\Controller;
 
 use OC\Contacts\ContactsMenu\Manager;
+use OCA\Core\ResponseDefinitions;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
-use OCP\Contacts\ContactsMenu\IEntry;
 use OCP\IRequest;
 use OCP\IUserSession;
 use OCP\Share\IShare;
 
+/**
+ * @psalm-import-type CoreContactsAction from ResponseDefinitions
+ */
 class HoverCardController extends \OCP\AppFramework\OCSController {
 	public function __construct(
 		IRequest $request,
@@ -43,6 +47,14 @@ class HoverCardController extends \OCP\AppFramework\OCSController {
 
 	/**
 	 * @NoAdminRequired
+	 *
+	 * Get the user details for a hovercard
+	 *
+	 * @param string $userId ID of the user
+	 * @return DataResponse<Http::STATUS_OK, array{userId: string, displayName: string, actions: CoreContactsAction[]}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 *
+	 * 200: User details returned
+	 * 404: User not found
 	 */
 	public function getUser(string $userId): DataResponse {
 		$contact = $this->manager->findOne($this->userSession->getUser(), IShare::TYPE_USER, $userId);
@@ -51,21 +63,18 @@ class HoverCardController extends \OCP\AppFramework\OCSController {
 			return new DataResponse([], Http::STATUS_NOT_FOUND);
 		}
 
-		$data = $this->entryToArray($contact);
+		$data = $contact->jsonSerialize();
 
 		$actions = $data['actions'];
 		if ($data['topAction']) {
 			array_unshift($actions, $data['topAction']);
 		}
 
+		/** @var CoreContactsAction[] $actions */
 		return new DataResponse([
 			'userId' => $userId,
 			'displayName' => $contact->getFullName(),
 			'actions' => $actions,
 		]);
 	}
-
-	protected function entryToArray(IEntry $entry): array {
-		return json_decode(json_encode($entry), true);
-	}
 }
diff --git a/core/Controller/JsController.php b/core/Controller/JsController.php
index 0ad78d5f87f..02e0c16b5a1 100644
--- a/core/Controller/JsController.php
+++ b/core/Controller/JsController.php
@@ -11,6 +11,7 @@ declare(strict_types=1);
  * @author Morris Jobke <hey@morrisjobke.de>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
  * @author Thomas Citharel <nextcloud@tcit.fr>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -33,6 +34,7 @@ namespace OC\Core\Controller;
 use OC\Files\AppData\Factory;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\FileDisplayResponse;
 use OCP\AppFramework\Http\NotFoundResponse;
 use OCP\AppFramework\Http\Response;
@@ -43,6 +45,7 @@ use OCP\Files\SimpleFS\ISimpleFile;
 use OCP\Files\SimpleFS\ISimpleFolder;
 use OCP\IRequest;
 
+#[IgnoreOpenAPI]
 class JsController extends Controller {
 	protected IAppData $appData;
 
diff --git a/core/Controller/LoginController.php b/core/Controller/LoginController.php
index 1bee366b00f..5f94c8f8a32 100644
--- a/core/Controller/LoginController.php
+++ b/core/Controller/LoginController.php
@@ -16,6 +16,7 @@ declare(strict_types=1);
  * @author Michael Weimann <mail@michael-weimann.eu>
  * @author Rayn0r <andrew@ilpss8.myfirewall.org>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license AGPL-3.0
  *
@@ -42,6 +43,7 @@ use OC\User\Session;
 use OC_App;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\Attribute\UseSession;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\Http\RedirectResponse;
@@ -58,6 +60,7 @@ use OCP\IUserManager;
 use OCP\Notification\IManager;
 use OCP\Util;
 
+#[IgnoreOpenAPI]
 class LoginController extends Controller {
 	public const LOGIN_MSG_INVALIDPASSWORD = 'invalidpassword';
 	public const LOGIN_MSG_USERDISABLED = 'userdisabled';
diff --git a/core/Controller/LostController.php b/core/Controller/LostController.php
index 7de93b7107a..9a1424c4c48 100644
--- a/core/Controller/LostController.php
+++ b/core/Controller/LostController.php
@@ -17,6 +17,7 @@
  * @author Roeland Jago Douma <roeland@famdouma.nl>
  * @author Thomas Müller <thomas.mueller@tmit.eu>
  * @author Victor Dubiniuk <dubiniuk@owncloud.com>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license AGPL-3.0
  *
@@ -37,6 +38,7 @@ namespace OC\Core\Controller;
 
 use Exception;
 use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\JSONResponse;
 use OCP\AppFramework\Http\TemplateResponse;
 use OCP\AppFramework\Services\IInitialState;
@@ -72,6 +74,7 @@ use function reset;
  *
  * @package OC\Core\Controller
  */
+#[IgnoreOpenAPI]
 class LostController extends Controller {
 	protected string $from;
 
diff --git a/core/Controller/NavigationController.php b/core/Controller/NavigationController.php
index 62c4dd98756..db1d67cc778 100644
--- a/core/Controller/NavigationController.php
+++ b/core/Controller/NavigationController.php
@@ -3,6 +3,7 @@
  * @copyright Copyright (c) 2018 Julius Härtl <jus@bitgrid.net>
  *
  * @author Julius Härtl <jus@bitgrid.net>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -22,6 +23,7 @@
  */
 namespace OC\Core\Controller;
 
+use OCA\Core\ResponseDefinitions;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
@@ -29,6 +31,9 @@ use OCP\INavigationManager;
 use OCP\IRequest;
 use OCP\IURLGenerator;
 
+/**
+ * @psalm-import-type CoreNavigationEntry from ResponseDefinitions
+ */
 class NavigationController extends OCSController {
 	public function __construct(
 		string $appName,
@@ -42,6 +47,14 @@ class NavigationController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 * @NoCSRFRequired
+	 *
+	 * Get the apps navigation
+	 *
+	 * @param bool $absolute Rewrite URLs to absolute ones
+	 * @return DataResponse<Http::STATUS_OK, CoreNavigationEntry[], array{}>|DataResponse<Http::STATUS_NOT_MODIFIED, array<empty>, array{}>
+	 *
+	 * 200: Apps navigation returned
+	 * 304: No apps navigation changed
 	 */
 	public function getAppsNavigation(bool $absolute = false): DataResponse {
 		$navigation = $this->navigationManager->getAll();
@@ -61,6 +74,14 @@ class NavigationController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 * @NoCSRFRequired
+	 *
+	 * Get the settings navigation
+	 *
+	 * @param bool $absolute Rewrite URLs to absolute ones
+	 * @return DataResponse<Http::STATUS_OK, CoreNavigationEntry[], array{}>|DataResponse<Http::STATUS_NOT_MODIFIED, array<empty>, array{}>
+	 *
+	 * 200: Apps navigation returned
+	 * 304: No apps navigation changed
 	 */
 	public function getSettingsNavigation(bool $absolute = false): DataResponse {
 		$navigation = $this->navigationManager->getAll('settings');
diff --git a/core/Controller/OCJSController.php b/core/Controller/OCJSController.php
index 48bd842e6e2..096242b5e9c 100644
--- a/core/Controller/OCJSController.php
+++ b/core/Controller/OCJSController.php
@@ -8,6 +8,7 @@
  * @author Lukas Reschke <lukas@statuscode.ch>
  * @author Morris Jobke <hey@morrisjobke.de>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -33,6 +34,7 @@ use OC\Template\JSConfigHelper;
 use OCP\App\IAppManager;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\DataDisplayResponse;
 use OCP\Defaults;
 use OCP\IConfig;
@@ -44,6 +46,7 @@ use OCP\IURLGenerator;
 use OCP\IUserSession;
 use OCP\L10N\IFactory;
 
+#[IgnoreOpenAPI]
 class OCJSController extends Controller {
 	private JSConfigHelper $helper;
 
diff --git a/core/Controller/OCSController.php b/core/Controller/OCSController.php
index 036cdfc2d60..64234a65634 100644
--- a/core/Controller/OCSController.php
+++ b/core/Controller/OCSController.php
@@ -8,6 +8,7 @@
  * @author Julius Härtl <jus@bitgrid.net>
  * @author Lukas Reschke <lukas@statuscode.ch>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -29,6 +30,8 @@ namespace OC\Core\Controller;
 
 use OC\CapabilitiesManager;
 use OC\Security\IdentityProof\Manager;
+use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\IRequest;
 use OCP\IUserManager;
@@ -49,6 +52,7 @@ class OCSController extends \OCP\AppFramework\OCSController {
 	/**
 	 * @PublicPage
 	 */
+	#[IgnoreOpenAPI]
 	public function getConfig(): DataResponse {
 		$data = [
 			'version' => '1.7',
@@ -63,14 +67,18 @@ class OCSController extends \OCP\AppFramework\OCSController {
 
 	/**
 	 * @PublicPage
+	 *
+	 * Get the capabilities
+	 *
+	 * @return DataResponse<Http::STATUS_OK, array{version: array{major: int, minor: int, micro: int, string: string, edition: '', extendedSupport: bool}, capabilities: array<string, mixed>}, array{}>
 	 */
 	public function getCapabilities(): DataResponse {
 		$result = [];
 		[$major, $minor, $micro] = \OCP\Util::getVersion();
 		$result['version'] = [
-			'major' => $major,
-			'minor' => $minor,
-			'micro' => $micro,
+			'major' => (int)$major,
+			'minor' => (int)$minor,
+			'micro' => (int)$micro,
 			'string' => \OC_Util::getVersionString(),
 			'edition' => '',
 			'extendedSupport' => \OCP\Util::hasExtendedSupport()
@@ -91,6 +99,7 @@ class OCSController extends \OCP\AppFramework\OCSController {
 	 * @PublicPage
 	 * @BruteForceProtection(action=login)
 	 */
+	#[IgnoreOpenAPI]
 	public function personCheck(string $login = '', string $password = ''): DataResponse {
 		if ($login !== '' && $password !== '') {
 			if ($this->userManager->checkPassword($login, $password)) {
@@ -111,6 +120,7 @@ class OCSController extends \OCP\AppFramework\OCSController {
 	/**
 	 * @PublicPage
 	 */
+	#[IgnoreOpenAPI]
 	public function getIdentityProof(string $cloudId): DataResponse {
 		$userObject = $this->userManager->get($cloudId);
 
diff --git a/core/Controller/PreviewController.php b/core/Controller/PreviewController.php
index 38373e2d147..c9183466f90 100644
--- a/core/Controller/PreviewController.php
+++ b/core/Controller/PreviewController.php
@@ -54,7 +54,20 @@ class PreviewController extends Controller {
 	 * @NoAdminRequired
 	 * @NoCSRFRequired
 	 *
-	 * @return DataResponse|FileDisplayResponse
+	 * Get a preview by file path
+	 *
+	 * @param string $file Path of the file
+	 * @param int $x Width of the preview
+	 * @param int $y Height of the preview
+	 * @param bool $a Whether to not crop the preview
+	 * @param bool $forceIcon Force returning an icon
+	 * @param string $mode How to crop the image
+	 * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 *
+	 * 200: Preview returned
+	 * 400: Getting preview is not possible
+	 * 403: Getting preview is not allowed
+	 * 404: Preview not found
 	 */
 	public function getPreview(
 		string $file = '',
@@ -81,7 +94,20 @@ class PreviewController extends Controller {
 	 * @NoAdminRequired
 	 * @NoCSRFRequired
 	 *
-	 * @return DataResponse|FileDisplayResponse
+	 * Get a preview by file ID
+	 *
+	 * @param int $fileId ID of the file
+	 * @param int $x Width of the preview
+	 * @param int $y Height of the preview
+	 * @param bool $a Whether to not crop the preview
+	 * @param bool $forceIcon Force returning an icon
+	 * @param string $mode How to crop the image
+	 * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 *
+	 * 200: Preview returned
+	 * 400: Getting preview is not possible
+	 * 403: Getting preview is not allowed
+	 * 404: Preview not found
 	 */
 	public function getPreviewByFileId(
 		int $fileId = -1,
@@ -107,7 +133,7 @@ class PreviewController extends Controller {
 	}
 
 	/**
-	 * @return DataResponse|FileDisplayResponse
+	 * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>
 	 */
 	private function fetchPreview(
 		Node $node,
diff --git a/core/Controller/ProfileApiController.php b/core/Controller/ProfileApiController.php
index e66d4f21c2b..ccbbc6c78bd 100644
--- a/core/Controller/ProfileApiController.php
+++ b/core/Controller/ProfileApiController.php
@@ -6,6 +6,7 @@ declare(strict_types=1);
  * @copyright 2021 Christopher Ng <chrng8@gmail.com>
  *
  * @author Christopher Ng <chrng8@gmail.com>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -27,6 +28,7 @@ declare(strict_types=1);
 namespace OC\Core\Controller;
 
 use OC\Core\Db\ProfileConfigMapper;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCS\OCSBadRequestException;
 use OCP\AppFramework\OCS\OCSForbiddenException;
@@ -53,6 +55,18 @@ class ProfileApiController extends OCSController {
 	 * @NoSubAdminRequired
 	 * @PasswordConfirmationRequired
 	 * @UserRateThrottle(limit=40, period=600)
+	 *
+	 * Update the visiblity of a parameter
+	 *
+	 * @param string $targetUserId ID of the user
+	 * @param string $paramId ID of the parameter
+	 * @param string $visibility New visibility
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @throws OCSBadRequestException Updating visibility is not possible
+	 * @throws OCSForbiddenException Not allowed to edit other users visibility
+	 * @throws OCSNotFoundException User not found
+	 *
+	 * 200: Visibility updated successfully
 	 */
 	public function setVisibility(string $targetUserId, string $paramId, string $visibility): DataResponse {
 		$requestingUser = $this->userSession->getUser();
diff --git a/core/Controller/ProfilePageController.php b/core/Controller/ProfilePageController.php
index 23dbf104b6b..5034a665684 100644
--- a/core/Controller/ProfilePageController.php
+++ b/core/Controller/ProfilePageController.php
@@ -6,6 +6,7 @@ declare(strict_types=1);
  * @copyright 2021 Christopher Ng <chrng8@gmail.com>
  *
  * @author Christopher Ng <chrng8@gmail.com>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -27,6 +28,7 @@ declare(strict_types=1);
 namespace OC\Core\Controller;
 
 use OC\Profile\ProfileManager;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\Profile\BeforeTemplateRenderedEvent;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http\TemplateResponse;
@@ -39,6 +41,7 @@ use OCP\Share\IManager as IShareManager;
 use OCP\UserStatus\IManager as IUserStatusManager;
 use OCP\EventDispatcher\IEventDispatcher;
 
+#[IgnoreOpenAPI]
 class ProfilePageController extends Controller {
 	public function __construct(
 		string $appName,
diff --git a/core/Controller/RecommendedAppsController.php b/core/Controller/RecommendedAppsController.php
index 5765b946613..5d2c2ba67ce 100644
--- a/core/Controller/RecommendedAppsController.php
+++ b/core/Controller/RecommendedAppsController.php
@@ -6,6 +6,7 @@ declare(strict_types=1);
  * @copyright 2019 Christoph Wurst <christoph@winzerhof-wurst.at>
  *
  * @author Christoph Wurst <christoph@winzerhof-wurst.at>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -26,12 +27,14 @@ declare(strict_types=1);
 namespace OC\Core\Controller;
 
 use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\Response;
 use OCP\AppFramework\Http\StandaloneTemplateResponse;
 use OCP\IInitialStateService;
 use OCP\IRequest;
 use OCP\IURLGenerator;
 
+#[IgnoreOpenAPI]
 class RecommendedAppsController extends Controller {
 	public function __construct(
 		IRequest $request,
diff --git a/core/Controller/ReferenceApiController.php b/core/Controller/ReferenceApiController.php
index 3df2e41c2a9..c16ca348d88 100644
--- a/core/Controller/ReferenceApiController.php
+++ b/core/Controller/ReferenceApiController.php
@@ -5,6 +5,7 @@ declare(strict_types=1);
  * @copyright Copyright (c) 2022 Julius Härtl <jus@bitgrid.net>
  *
  * @author Julius Härtl <jus@bitgrid.net>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -24,11 +25,18 @@ declare(strict_types=1);
 
 namespace OC\Core\Controller;
 
+use OCA\Core\ResponseDefinitions;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\Collaboration\Reference\IDiscoverableReferenceProvider;
 use OCP\Collaboration\Reference\IReferenceManager;
+use OCP\Collaboration\Reference\Reference;
 use OCP\IRequest;
 
+/**
+ * @psalm-import-type CoreReference from ResponseDefinitions
+ * @psalm-import-type CoreReferenceProvider from ResponseDefinitions
+ */
 class ReferenceApiController extends \OCP\AppFramework\OCSController {
 	public function __construct(
 		string $appName,
@@ -41,6 +49,13 @@ class ReferenceApiController extends \OCP\AppFramework\OCSController {
 
 	/**
 	 * @NoAdminRequired
+	 *
+	 * Extract references from a text
+	 *
+	 * @param string $text Text to extract from
+	 * @param bool $resolve Resolve the references
+	 * @param int $limit Maximum amount of references to extract
+	 * @return DataResponse<Http::STATUS_OK, array{references: array<string, CoreReference|mixed|null>}, array{}>
 	 */
 	public function extract(string $text, bool $resolve = false, int $limit = 1): DataResponse {
 		$references = $this->referenceManager->extractReferences($text);
@@ -52,7 +67,7 @@ class ReferenceApiController extends \OCP\AppFramework\OCSController {
 				break;
 			}
 
-			$result[$reference] = $resolve ? $this->referenceManager->resolveReference($reference) : null;
+			$result[$reference] = $resolve ? $this->referenceManager->resolveReference($reference)->jsonSerialize() : null;
 		}
 
 		return new DataResponse([
@@ -62,11 +77,17 @@ class ReferenceApiController extends \OCP\AppFramework\OCSController {
 
 	/**
 	 * @NoAdminRequired
+	 *
+	 * Resolve a reference
+	 *
+	 * @param string $reference Reference to resolve
+	 * @return DataResponse<Http::STATUS_OK, array{references: array<string, ?CoreReference>}, array{}>
 	 */
 	public function resolveOne(string $reference): DataResponse {
-		$resolvedReference = $this->referenceManager->resolveReference(trim($reference));
+		/** @var ?CoreReference $resolvedReference */
+		$resolvedReference = $this->referenceManager->resolveReference(trim($reference))?->jsonSerialize();
 
-		$response = new DataResponse(['references' => [ $reference => $resolvedReference ]]);
+		$response = new DataResponse(['references' => [$reference => $resolvedReference]]);
 		$response->cacheFor(3600, false, true);
 		return $response;
 	}
@@ -74,7 +95,11 @@ class ReferenceApiController extends \OCP\AppFramework\OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param string[] $references
+	 * Resolve multiple references
+	 *
+	 * @param string[] $references References to resolve
+	 * @param int $limit Maximum amount of references to resolve
+	 * @return DataResponse<Http::STATUS_OK, array{references: array<string, CoreReference|mixed|null>}, array{}>
 	 */
 	public function resolve(array $references, int $limit = 1): DataResponse {
 		$result = [];
@@ -84,16 +109,20 @@ class ReferenceApiController extends \OCP\AppFramework\OCSController {
 				break;
 			}
 
-			$result[$reference] = $this->referenceManager->resolveReference($reference);
+			$result[$reference] = $this->referenceManager->resolveReference($reference)?->jsonSerialize();
 		}
 
 		return new DataResponse([
-			'references' => array_filter($result)
+			'references' => $result
 		]);
 	}
 
 	/**
 	 * @NoAdminRequired
+	 *
+	 * Get the providers
+	 *
+	 * @return DataResponse<Http::STATUS_OK, CoreReferenceProvider[], array{}>
 	 */
 	public function getProvidersInfo(): DataResponse {
 		$providers = $this->referenceManager->getDiscoverableProviders();
@@ -105,6 +134,12 @@ class ReferenceApiController extends \OCP\AppFramework\OCSController {
 
 	/**
 	 * @NoAdminRequired
+	 *
+	 * Touch a provider
+	 *
+	 * @param string $providerId ID of the provider
+	 * @param int|null $timestamp Timestamp of the last usage
+	 * @return DataResponse<Http::STATUS_OK, array{success: bool}, array{}>
 	 */
 	public function touchProvider(string $providerId, ?int $timestamp = null): DataResponse {
 		if ($this->userId !== null) {
diff --git a/core/Controller/ReferenceController.php b/core/Controller/ReferenceController.php
index a8a489aeeab..cec2dc90cf5 100644
--- a/core/Controller/ReferenceController.php
+++ b/core/Controller/ReferenceController.php
@@ -5,6 +5,7 @@ declare(strict_types=1);
  * @copyright Copyright (c) 2022 Julius Härtl <jus@bitgrid.net>
  *
  * @author Julius Härtl <jus@bitgrid.net>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -24,7 +25,6 @@ declare(strict_types=1);
 
 namespace OC\Core\Controller;
 
-use OCP\AppFramework\Http\Response;
 use OCP\Collaboration\Reference\IReferenceManager;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
@@ -48,10 +48,16 @@ class ReferenceController extends Controller {
 	/**
 	 * @PublicPage
 	 * @NoCSRFRequired
+	 *
+	 * Get a preview for a reference
+	 *
 	 * @param string $referenceId the reference cache key
-	 * @return Response
+	 * @return DataDownloadResponse<Http::STATUS_OK, string, array{}>|DataResponse<Http::STATUS_NOT_FOUND, '', array{}>
+	 *
+	 * 200: Preview returned
+	 * 404: Reference not found
 	 */
-	public function preview(string $referenceId): Response {
+	public function preview(string $referenceId): DataDownloadResponse|DataResponse {
 		$reference = $this->referenceManager->getReferenceByCacheKey($referenceId);
 
 		try {
diff --git a/core/Controller/TranslationApiController.php b/core/Controller/TranslationApiController.php
index c1628c24555..3f70a5bcb05 100644
--- a/core/Controller/TranslationApiController.php
+++ b/core/Controller/TranslationApiController.php
@@ -6,6 +6,7 @@ declare(strict_types=1);
  * @copyright Copyright (c) 2022 Julius Härtl <jus@bitgrid.net>
  *
  * @author Julius Härtl <jus@bitgrid.net>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -47,10 +48,14 @@ class TranslationApiController extends \OCP\AppFramework\OCSController {
 
 	/**
 	 * @PublicPage
+	 *
+	 * Get the list of supported languages
+	 *
+	 * @return DataResponse<Http::STATUS_OK, array{languages: array{from: string, fromLabel: string, to: string, toLabel: string}[], languageDetection: bool}, array{}>
 	 */
 	public function languages(): DataResponse {
 		return new DataResponse([
-			'languages' => $this->translationManager->getLanguages(),
+			'languages' => array_map(fn ($lang) => $lang->jsonSerialize(), $this->translationManager->getLanguages()),
 			'languageDetection' => $this->translationManager->canDetectLanguage(),
 		]);
 	}
@@ -59,6 +64,17 @@ class TranslationApiController extends \OCP\AppFramework\OCSController {
 	 * @PublicPage
 	 * @UserRateThrottle(limit=25, period=120)
 	 * @AnonRateThrottle(limit=10, period=120)
+	 *
+	 * Translate a text
+	 *
+	 * @param string $text Text to be translated
+	 * @param string|null $fromLanguage Language to translate from
+	 * @param string $toLanguage Language to translate to
+	 * @return DataResponse<Http::STATUS_OK, array{text: string, from: ?string}, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_PRECONDITION_FAILED|Http::STATUS_INTERNAL_SERVER_ERROR, array{message: string, from?: ?string}, array{}>
+	 *
+	 * 200: Translated text returned
+	 * 400: Language not detected or unable to translate
+	 * 412: Translating is not possible
 	 */
 	public function translate(string $text, ?string $fromLanguage, string $toLanguage): DataResponse {
 		try {
diff --git a/core/Controller/TwoFactorChallengeController.php b/core/Controller/TwoFactorChallengeController.php
index 40b100c41bd..172d0240f20 100644
--- a/core/Controller/TwoFactorChallengeController.php
+++ b/core/Controller/TwoFactorChallengeController.php
@@ -7,6 +7,7 @@
  * @author Joas Schilling <coding@schilljs.com>
  * @author Lukas Reschke <lukas@statuscode.ch>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license AGPL-3.0
  *
@@ -28,6 +29,7 @@ namespace OC\Core\Controller;
 use OC\Authentication\TwoFactorAuth\Manager;
 use OC_User;
 use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\Attribute\UseSession;
 use OCP\AppFramework\Http\RedirectResponse;
 use OCP\AppFramework\Http\StandaloneTemplateResponse;
@@ -41,6 +43,7 @@ use OCP\IURLGenerator;
 use OCP\IUserSession;
 use Psr\Log\LoggerInterface;
 
+#[IgnoreOpenAPI]
 class TwoFactorChallengeController extends Controller {
 	public function __construct(
 		string $appName,
diff --git a/core/Controller/UnifiedSearchController.php b/core/Controller/UnifiedSearchController.php
index 7e73ac8100f..346717599e0 100644
--- a/core/Controller/UnifiedSearchController.php
+++ b/core/Controller/UnifiedSearchController.php
@@ -8,6 +8,7 @@ declare(strict_types=1);
  * @author Christoph Wurst <christoph@winzerhof-wurst.at>
  * @author Joas Schilling <coding@schilljs.com>
  * @author John Molakvoæ <skjnldsv@protonmail.com>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -29,6 +30,7 @@ namespace OC\Core\Controller;
 
 use OC\Search\SearchComposer;
 use OC\Search\SearchQuery;
+use OCA\Core\ResponseDefinitions;
 use OCP\AppFramework\OCSController;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
@@ -39,6 +41,10 @@ use OCP\Route\IRouter;
 use OCP\Search\ISearchQuery;
 use Symfony\Component\Routing\Exception\ResourceNotFoundException;
 
+/**
+ * @psalm-import-type CoreUnifiedSearchProvider from ResponseDefinitions
+ * @psalm-import-type CoreUnifiedSearchResult from ResponseDefinitions
+ */
 class UnifiedSearchController extends OCSController {
 	public function __construct(
 		IRequest $request,
@@ -54,7 +60,10 @@ class UnifiedSearchController extends OCSController {
 	 * @NoAdminRequired
 	 * @NoCSRFRequired
 	 *
+	 * Get the providers for unified search
+	 *
 	 * @param string $from the url the user is currently at
+	 * @return DataResponse<Http::STATUS_OK, CoreUnifiedSearchProvider[], array{}>
 	 */
 	public function getProviders(string $from = ''): DataResponse {
 		[$route, $parameters] = $this->getRouteInformation($from);
@@ -69,14 +78,19 @@ class UnifiedSearchController extends OCSController {
 	 * @NoAdminRequired
 	 * @NoCSRFRequired
 	 *
-	 * @param string $providerId
-	 * @param string $term
-	 * @param int|null $sortOrder
-	 * @param int|null $limit
-	 * @param int|string|null $cursor
-	 * @param string $from
+	 * Search
+	 *
+	 * @param string $providerId ID of the provider
+	 * @param string $term Term to search
+	 * @param int|null $sortOrder Order of entries
+	 * @param int|null $limit Maximum amount of entries
+	 * @param int|string|null $cursor Offset for searching
+	 * @param string $from The current user URL
+	 *
+	 * @return DataResponse<Http::STATUS_OK, CoreUnifiedSearchResult, array{}>|DataResponse<Http::STATUS_BAD_REQUEST, null, array{}>
 	 *
-	 * @return DataResponse
+	 * 200: Search entries returned
+	 * 400: Searching is not possible
 	 */
 	public function search(string $providerId,
 						   string $term = '',
@@ -101,7 +115,7 @@ class UnifiedSearchController extends OCSController {
 					$route,
 					$routeParameters
 				)
-			)
+			)->jsonSerialize()
 		);
 	}
 
diff --git a/core/Controller/UnsupportedBrowserController.php b/core/Controller/UnsupportedBrowserController.php
index 8cdc190deea..d736401c218 100644
--- a/core/Controller/UnsupportedBrowserController.php
+++ b/core/Controller/UnsupportedBrowserController.php
@@ -6,6 +6,7 @@ declare(strict_types=1);
  * @copyright 2021 John Molakvoæ <skjnldsv@protonmail.com>
  *
  * @author John Molakvoæ <skjnldsv@protonmail.com>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -27,11 +28,13 @@ declare(strict_types=1);
 namespace OC\Core\Controller;
 
 use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\Response;
 use OCP\AppFramework\Http\TemplateResponse;
 use OCP\IRequest;
 use OCP\Util;
 
+#[IgnoreOpenAPI]
 class UnsupportedBrowserController extends Controller {
 	public function __construct(IRequest $request) {
 		parent::__construct('core', $request);
diff --git a/core/Controller/WalledGardenController.php b/core/Controller/WalledGardenController.php
index 0079cc5a69a..b1668bb6d97 100644
--- a/core/Controller/WalledGardenController.php
+++ b/core/Controller/WalledGardenController.php
@@ -4,6 +4,7 @@
  *
  * @author Christoph Wurst <christoph@winzerhof-wurst.at>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -25,8 +26,10 @@ namespace OC\Core\Controller;
 
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\Response;
 
+#[IgnoreOpenAPI]
 class WalledGardenController extends Controller {
 	/**
 	 * @PublicPage
diff --git a/core/Controller/WellKnownController.php b/core/Controller/WellKnownController.php
index 2e317ae01b5..a4fd1689cdf 100644
--- a/core/Controller/WellKnownController.php
+++ b/core/Controller/WellKnownController.php
@@ -6,6 +6,7 @@ declare(strict_types=1);
  * @copyright 2020 Christoph Wurst <christoph@winzerhof-wurst.at>
  *
  * @author Christoph Wurst <christoph@winzerhof-wurst.at>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -28,10 +29,12 @@ namespace OC\Core\Controller;
 use OC\Http\WellKnown\RequestManager;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\JSONResponse;
 use OCP\AppFramework\Http\Response;
 use OCP\IRequest;
 
+#[IgnoreOpenAPI]
 class WellKnownController extends Controller {
 	public function __construct(
 		IRequest $request,
diff --git a/core/Controller/WhatsNewController.php b/core/Controller/WhatsNewController.php
index 0791ce616f5..2d48f3cc485 100644
--- a/core/Controller/WhatsNewController.php
+++ b/core/Controller/WhatsNewController.php
@@ -4,6 +4,7 @@
  *
  * @author Arthur Schiwon <blizzz@arthur-schiwon.de>
  * @author Christoph Wurst <christoph@winzerhof-wurst.at>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -54,6 +55,13 @@ class WhatsNewController extends OCSController {
 
 	/**
 	 * @NoAdminRequired
+	 *
+	 * Get the changes
+	 *
+	 * @return DataResponse<Http::STATUS_OK, array{changelogURL: string, product: string, version: string, whatsNew?: array{regular: string[], admin: string[]}}, array{}>|DataResponse<Http::STATUS_NO_CONTENT, array<empty>, array{}>
+	 *
+	 * 200: Changes returned
+	 * 204: No changes
 	 */
 	public function get():DataResponse {
 		$user = $this->userSession->getUser();
@@ -92,8 +100,15 @@ class WhatsNewController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
+	 * Dismiss the changes
+	 *
+	 * @param string $version Version to dismiss the changes for
+	 *
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
 	 * @throws \OCP\PreConditionNotMetException
 	 * @throws DoesNotExistException
+	 *
+	 * 200: Changes dismissed
 	 */
 	public function dismiss(string $version):DataResponse {
 		$user = $this->userSession->getUser();
diff --git a/core/Controller/WipeController.php b/core/Controller/WipeController.php
index 6ffb950ca86..537fd7126f6 100644
--- a/core/Controller/WipeController.php
+++ b/core/Controller/WipeController.php
@@ -6,6 +6,7 @@ declare(strict_types=1);
  * @copyright Copyright (c) 2019, Roeland Jago Douma <roeland@famdouma.nl>
  *
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -48,9 +49,14 @@ class WipeController extends Controller {
 	 *
 	 * @AnonRateThrottle(limit=10, period=300)
 	 *
-	 * @param string $token
+	 * Check if the device should be wiped
 	 *
-	 * @return JSONResponse
+	 * @param string $token App password
+	 *
+	 * @return JSONResponse<Http::STATUS_OK, array{wipe: bool}, array{}>|JSONResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 *
+	 * 200: Device should be wiped
+	 * 404: Device should not be wiped
 	 */
 	public function checkWipe(string $token): JSONResponse {
 		try {
@@ -74,9 +80,14 @@ class WipeController extends Controller {
 	 *
 	 * @AnonRateThrottle(limit=10, period=300)
 	 *
-	 * @param string $token
+	 * Finish the wipe
+	 *
+	 * @param string $token App password
+	 *
+	 * @return JSONResponse<Http::STATUS_OK|Http::STATUS_NOT_FOUND, array<empty>, array{}>
 	 *
-	 * @return JSONResponse
+	 * 200: Wipe finished successfully
+	 * 404: Device should not be wiped
 	 */
 	public function wipeDone(string $token): JSONResponse {
 		try {