Merge pull request #39287 from nextcloud/feature/openapi/theming

theming: Add OpenAPI spec

apps/theming/composer/composer/autoload_classmap.php

@@ -22,6 +22,7 @@
     'OCA\\Theming\\Migration\\InitBackgroundImagesMigration' => $baseDir . '/../lib/Migration/InitBackgroundImagesMigration.php',
     'OCA\\Theming\\Migration\\MigrateAdminConfig' => $baseDir . '/../lib/Migration/MigrateAdminConfig.php',
     'OCA\\Theming\\Migration\\MigrateUserConfig' => $baseDir . '/../lib/Migration/MigrateUserConfig.php',
+    'OCA\\Theming\\ResponseDefinitions' => $baseDir . '/../lib/ResponseDefinitions.php',
     'OCA\\Theming\\Service\\BackgroundService' => $baseDir . '/../lib/Service/BackgroundService.php',
     'OCA\\Theming\\Service\\JSDataService' => $baseDir . '/../lib/Service/JSDataService.php',
     'OCA\\Theming\\Service\\ThemeInjectionService' => $baseDir . '/../lib/Service/ThemeInjectionService.php',

apps/theming/composer/composer/autoload_static.php

@@ -37,6 +37,7 @@ class ComposerStaticInitTheming
         'OCA\\Theming\\Migration\\InitBackgroundImagesMigration' => __DIR__ . '/..' . '/../lib/Migration/InitBackgroundImagesMigration.php',
         'OCA\\Theming\\Migration\\MigrateAdminConfig' => __DIR__ . '/..' . '/../lib/Migration/MigrateAdminConfig.php',
         'OCA\\Theming\\Migration\\MigrateUserConfig' => __DIR__ . '/..' . '/../lib/Migration/MigrateUserConfig.php',
+        'OCA\\Theming\\ResponseDefinitions' => __DIR__ . '/..' . '/../lib/ResponseDefinitions.php',
         'OCA\\Theming\\Service\\BackgroundService' => __DIR__ . '/..' . '/../lib/Service/BackgroundService.php',
         'OCA\\Theming\\Service\\JSDataService' => __DIR__ . '/..' . '/../lib/Service/JSDataService.php',
         'OCA\\Theming\\Service\\ThemeInjectionService' => __DIR__ . '/..' . '/../lib/Service/ThemeInjectionService.php',

apps/theming/lib/Capabilities.php

@@ -7,6 +7,7 @@
  * @author Julien Veyssier <[email protected]>
  * @author Julius Härtl <[email protected]>
  * @author Morris Jobke <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -64,6 +65,25 @@ public function __construct(ThemingDefaults $theming, Util $util, IURLGenerator
 
 	/**
 	 * Return this classes capabilities
+	 *
+	 * @return array{
+	 *     theming: array{
+	 *         name: string,
+	 *         url: string,
+	 *         slogan: string,
+	 *         color: string,
+	 *         color-text: string,
+	 *         color-element: string,
+	 *         color-element-bright: string,
+	 *         color-element-dark: string,
+	 *         logo: string,
+	 *         background: string,
+	 *         background-plain: bool,
+	 *         background-default: bool,
+	 *         logoheader: string,
+	 *         favicon: string,
+	 *     },
+	 * }
 	 */
 	public function getCapabilities() {
 		$backgroundLogo = $this->config->getAppValue('theming', 'backgroundMime', '');

apps/theming/lib/Controller/IconController.php

@@ -8,6 +8,7 @@
  * @author Julius Härtl <[email protected]>
  * @author Michael Weimann <[email protected]>
  * @author Roeland Jago Douma <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -80,10 +81,15 @@ public function __construct(
 	 * @PublicPage
 	 * @NoCSRFRequired
 	 *
-	 * @param $app string app name
-	 * @param $image string image file name (svg required)
-	 * @return FileDisplayResponse|NotFoundResponse
+	 * Get a themed icon
+	 *
+	 * @param string $app ID of the app
+	 * @param string $image image file name (svg required)
+	 * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: 'image/svg+xml'}>|NotFoundResponse<Http::STATUS_NOT_FOUND, array{}>
 	 * @throws \Exception
+	 *
+	 * 200: Themed icon returned
+	 * 404: Themed icon not found
 	 */
 	public function getThemedIcon(string $app, string $image): Response {
 		$color = $this->themingDefaults->getColorPrimary();
@@ -107,9 +113,12 @@ public function getThemedIcon(string $app, string $image): Response {
 	 * @PublicPage
 	 * @NoCSRFRequired
 	 *
-	 * @param $app string app name
-	 * @return FileDisplayResponse|DataDisplayResponse|NotFoundResponse
+	 * @param string $app ID of the app
+	 * @return DataDisplayResponse<Http::STATUS_OK, array{Content-Type: 'image/x-icon'}>|FileDisplayResponse<Http::STATUS_OK, array{Content-Type: 'image/x-icon'}>|NotFoundResponse<Http::STATUS_NOT_FOUND, array{}>
 	 * @throws \Exception
+	 *
+	 * 200: Favicon returned
+	 * 404: Favicon not found
 	 */
 	public function getFavicon(string $app = 'core'): Response {
 		$response = null;
@@ -146,9 +155,12 @@ public function getFavicon(string $app = 'core'): Response {
 	 * @PublicPage
 	 * @NoCSRFRequired
 	 *
-	 * @param $app string app name
-	 * @return DataDisplayResponse|FileDisplayResponse|NotFoundResponse
+	 * @param string $app ID of the app
+	 * @return DataDisplayResponse<Http::STATUS_OK, array{Content-Type: 'image/png'}>|FileDisplayResponse<Http::STATUS_OK, array{Content-Type: 'image/x-icon'|'image/png'}>|NotFoundResponse<Http::STATUS_NOT_FOUND, array{}>
 	 * @throws \Exception
+	 *
+	 * 200: Touch icon returned
+	 * 404: Touch icon not found
 	 */
 	public function getTouchIcon(string $app = 'core'): Response {
 		$response = null;

apps/theming/lib/Controller/ThemingController.php

@@ -18,6 +18,7 @@
  * @author Robin Appelman <[email protected]>
  * @author Roeland Jago Douma <[email protected]>
  * @author Thomas Citharel <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -46,6 +47,7 @@
 use OCP\AppFramework\Http\DataDisplayResponse;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\Http\FileDisplayResponse;
+use OCP\AppFramework\Http\JSONResponse;
 use OCP\AppFramework\Http\NotFoundResponse;
 use OCP\Files\IAppData;
 use OCP\Files\NotFoundException;
@@ -314,10 +316,15 @@ public function undoAll(): DataResponse {
 	 * @NoCSRFRequired
 	 * @NoSameSiteCookieRequired
 	 *
-	 * @param string $key
-	 * @param bool $useSvg
-	 * @return FileDisplayResponse|NotFoundResponse
+	 * Get an image
+	 *
+	 * @param string $key Key of the image
+	 * @param bool $useSvg Return image as SVG
+	 * @return FileDisplayResponse<Http::STATUS_OK, array{}>|NotFoundResponse<Http::STATUS_NOT_FOUND, array{}>
 	 * @throws NotPermittedException
+	 *
+	 * 200: Image returned
+	 * 404: Image not found
 	 */
 	public function getImage(string $key, bool $useSvg = true) {
 		try {
@@ -347,7 +354,15 @@ public function getImage(string $key, bool $useSvg = true) {
 	 * @NoSameSiteCookieRequired
 	 * @NoTwoFactorRequired
 	 *
-	 * @return DataDisplayResponse|NotFoundResponse
+	 * Get the CSS stylesheet for a theme
+	 *
+	 * @param string $themeId ID of the theme
+	 * @param bool $plain Let the browser decide the CSS priority
+	 * @param bool $withCustomCss Include custom CSS
+	 * @return DataDisplayResponse<Http::STATUS_OK, array{Content-Type: 'text/css'}>|NotFoundResponse<Http::STATUS_NOT_FOUND, array{}>
+	 *
+	 * 200: Stylesheet returned
+	 * 404: Theme not found
 	 */
 	public function getThemeStylesheet(string $themeId, bool $plain = false, bool $withCustomCss = false) {
 		$themes = $this->themesService->getThemes();
@@ -387,9 +402,13 @@ public function getThemeStylesheet(string $themeId, bool $plain = false, bool $w
 	 * @NoCSRFRequired
 	 * @PublicPage
 	 *
-	 * @return Http\JSONResponse
+	 * Get the manifest for an app
+	 *
+	 * @param string $app ID of the app
+	 * @psalm-suppress LessSpecificReturnStatement The content of the Manifest doesn't need to be described in the return type
+	 * @return JSONResponse<Http::STATUS_OK, array{name: string, short_name: string, start_url: string, theme_color: string, background_color: string, description: string, icons: array{src: non-empty-string, type: string, sizes: string}[], display: string}, array{}>
 	 */
-	public function getManifest($app) {
+	public function getManifest(string $app) {
 		$cacheBusterValue = $this->config->getAppValue('theming', 'cachebuster', '0');
 		if ($app === 'core' || $app === 'settings') {
 			$name = $this->themingDefaults->getName();
@@ -407,6 +426,10 @@ public function getManifest($app) {
 			}
 			$description = $info['summary'] ?? '';
 		}
+		/**
+		 * @var string $description
+		 * @var string $shortName
+		 */
 		$responseJS = [
 			'name' => $name,
 			'short_name' => $shortName,
@@ -431,7 +454,7 @@ public function getManifest($app) {
 				],
 			'display' => 'standalone'
 		];
-		$response = new Http\JSONResponse($responseJS);
+		$response = new JSONResponse($responseJS);
 		$response->cacheFor(3600);
 		return $response;
 	}

apps/theming/lib/Controller/UserThemeController.php

@@ -11,6 +11,7 @@
  * @author Janis Köhr <[email protected]>
  * @author John Molakvoæ <[email protected]>
  * @author Roeland Jago Douma <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -32,6 +33,7 @@
 
 use OCA\Theming\AppInfo\Application;
 use OCA\Theming\ITheme;
+use OCA\Theming\ResponseDefinitions;
 use OCA\Theming\Service\BackgroundService;
 use OCA\Theming\Service\ThemesService;
 use OCA\Theming\ThemingDefaults;
@@ -48,10 +50,13 @@
 use OCP\IUserSession;
 use OCP\PreConditionNotMetException;
 
+/**
+ * @psalm-import-type ThemingBackground from ResponseDefinitions
+ */
 class UserThemeController extends OCSController {
 
 	protected ?string $userId = null;
-	
+
 	private IConfig $config;
 	private IUserSession $userSession;
 	private ThemesService $themesService;
@@ -84,8 +89,11 @@ public function __construct(string $appName,
 	 * Enable theme
 	 *
 	 * @param string $themeId the theme ID
-	 * @return DataResponse
-	 * @throws OCSBadRequestException|PreConditionNotMetException
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @throws OCSBadRequestException Enabling theme is not possible
+	 * @throws PreConditionNotMetException
+	 *
+	 * 200: Theme enabled successfully
 	 */
 	public function enableTheme(string $themeId): DataResponse {
 		$theme = $this->validateTheme($themeId);
@@ -101,8 +109,11 @@ public function enableTheme(string $themeId): DataResponse {
 	 * Disable theme
 	 *
 	 * @param string $themeId the theme ID
-	 * @return DataResponse
-	 * @throws OCSBadRequestException|PreConditionNotMetException
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @throws OCSBadRequestException Disabling theme is not possible
+	 * @throws PreConditionNotMetException
+	 *
+	 * 200: Theme disabled successfully
 	 */
 	public function disableTheme(string $themeId): DataResponse {
 		$theme = $this->validateTheme($themeId);
@@ -119,7 +130,8 @@ public function disableTheme(string $themeId): DataResponse {
 	 *
 	 * @param string $themeId the theme ID
 	 * @return ITheme
-	 * @throws OCSBadRequestException|PreConditionNotMetException
+	 * @throws OCSBadRequestException
+	 * @throws PreConditionNotMetException
 	 */
 	private function validateTheme(string $themeId): ITheme {
 		if ($themeId === '' || !$themeId) {
@@ -143,6 +155,12 @@ private function validateTheme(string $themeId): ITheme {
 	/**
 	 * @NoAdminRequired
 	 * @NoCSRFRequired
+	 *
+	 * Get the background image
+	 * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|NotFoundResponse<Http::STATUS_NOT_FOUND, array{}>
+	 *
+	 * 200: Background image returned
+	 * 404: Background image not found
 	 */
 	public function getBackground(): Http\Response {
 		$file = $this->backgroundService->getBackground();
@@ -156,6 +174,10 @@ public function getBackground(): Http\Response {
 
 	/**
 	 * @NoAdminRequired
+	 *
+	 * Delete the background
+	 *
+	 * @return JSONResponse<Http::STATUS_OK, ThemingBackground, array{}>
 	 */
 	public function deleteBackground(): JSONResponse {
 		$currentVersion = (int)$this->config->getUserValue($this->userId, Application::APP_ID, 'userCacheBuster', '0');
@@ -169,6 +191,16 @@ public function deleteBackground(): JSONResponse {
 
 	/**
 	 * @NoAdminRequired
+	 *
+	 * Set the background
+	 *
+	 * @param string $type Type of background
+	 * @param string $value Path of the background image
+	 * @param string|null $color Color for the background
+	 * @return JSONResponse<Http::STATUS_OK, ThemingBackground, array{}>|JSONResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_INTERNAL_SERVER_ERROR, array{error: string}, array{}>
+	 *
+	 * 200: Background set successfully
+	 * 400: Setting background is not possible
 	 */
 	public function setBackground(string $type = BackgroundService::BACKGROUND_DEFAULT, string $value = '', string $color = null): JSONResponse {
 		$currentVersion = (int)$this->config->getUserValue($this->userId, Application::APP_ID, 'userCacheBuster', '0');

apps/theming/lib/ResponseDefinitions.php

@@ -0,0 +1,36 @@
+<?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\Theming;
+
+/**
+ * @psalm-type ThemingBackground = array{
+ *     backgroundImage: ?string,
+ *     backgroundColor: string,
+ *     version: int,
+ * }
+ */
+class ResponseDefinitions {
+}