core: Add OpenAPI spec

Signed-off-by: jld3103 <jld3103yt@gmail.com>
nextcloud · Jul 13, 2023 · c4b6096 · c4b6096
1 parent 706c141
commit c4b6096
Show file tree

Hide file tree

Showing 39 changed files with 686 additions and 283 deletions.
diff --git a/core/Controller/AppPasswordController.php b/core/Controller/AppPasswordController.php
@@ -8,6 +8,7 @@
  * @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\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 @@ public function __construct(
 	/**
 	 * @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 @@ public function getAppPassword(): DataResponse {
 
 	/**
 	 * @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 @@ public function deleteAppPassword(): DataResponse {
 
 	/**
 	 * @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
@@ -30,6 +30,8 @@
  */
 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\IRequest;
 use OCP\Share\IShare;
 
+/**
+ * @psalm-import-type CoreAutocompleteResult from ResponseDefinitions
+ */
 class AutoCompleteController extends OCSController {
 	public function __construct(
 		string $appName,
@@ -52,7 +57,17 @@ public function __construct(
 
 	/**
 	 * @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 @@ public function get(string $search, ?string $itemType, ?string $itemId, ?string
 		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
@@ -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 @@ public function __construct(
 	 * @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 @@ public function getAvatarDark(string $userId, int $size) {
 	 * @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
@@ -7,6 +7,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
  *
@@ -29,9 +30,11 @@
 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
@@ -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\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\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
@@ -31,8 +31,10 @@
 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\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 @@ public function __construct(
 	/**
 	 * @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 @@ public function poll(string $token): JSONResponse {
 			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 @@ public function landing(string $token, $user = ''): Response {
 	 * @NoCSRFRequired
 	 * @PublicPage
 	 */
+	#[IgnoreOpenAPI]
 	#[UseSession]
 	public function showAuthPickerPage($user = ''): StandaloneTemplateResponse {
 		try {
@@ -134,6 +150,7 @@ public function showAuthPickerPage($user = ''): StandaloneTemplateResponse {
 	 * @NoCSRFRequired
 	 * @NoSameSiteCookieRequired
 	 */
+	#[IgnoreOpenAPI]
 	#[UseSession]
 	public function grantPage(?string $stateToken): StandaloneTemplateResponse {
 		if ($stateToken === null) {
@@ -267,6 +284,10 @@ private function handleFlowDone(bool $result): StandaloneTemplateResponse {
 	/**
 	 * @NoCSRFRequired
 	 * @PublicPage
+	 *
+	 * Init a login flow
+	 *
+	 * @return JSONResponse<Http::STATUS_OK, CoreLoginFlowV2, array{}>
 	 */
 	public function init(): JSONResponse {
 		// Get client user agent