dashboard: Add OpenAPI spec

apps/dashboard/composer/composer/autoload_classmap.php

@@ -10,4 +10,5 @@
     'OCA\\Dashboard\\Controller\\DashboardApiController' => $baseDir . '/../lib/Controller/DashboardApiController.php',
     'OCA\\Dashboard\\Controller\\DashboardController' => $baseDir . '/../lib/Controller/DashboardController.php',
     'OCA\\Dashboard\\Controller\\LayoutApiController' => $baseDir . '/../lib/Controller/LayoutApiController.php',
+    'OCA\\Dashboard\\ResponseDefinitions' => $baseDir . '/../lib/ResponseDefinitions.php',
 );

apps/dashboard/composer/composer/autoload_static.php

@@ -25,6 +25,7 @@ class ComposerStaticInitDashboard
         'OCA\\Dashboard\\Controller\\DashboardApiController' => __DIR__ . '/..' . '/../lib/Controller/DashboardApiController.php',
         'OCA\\Dashboard\\Controller\\DashboardController' => __DIR__ . '/..' . '/../lib/Controller/DashboardController.php',
         'OCA\\Dashboard\\Controller\\LayoutApiController' => __DIR__ . '/..' . '/../lib/Controller/LayoutApiController.php',
+        'OCA\\Dashboard\\ResponseDefinitions' => __DIR__ . '/..' . '/../lib/ResponseDefinitions.php',
     );
 
     public static function getInitializer(ClassLoader $loader)

apps/dashboard/lib/Controller/DashboardApiController.php

@@ -6,6 +6,7 @@
  * @copyright Copyright (c) 2021 Julien Veyssier <[email protected]>
  *
  * @author Julien Veyssier <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -26,7 +27,9 @@
 
 namespace OCA\Dashboard\Controller;
 
+use OCA\Dashboard\ResponseDefinitions;
 use OCP\AppFramework\OCSController;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\Dashboard\IButtonWidget;
 use OCP\Dashboard\IIconWidget;
@@ -41,6 +44,10 @@
 use OCP\Dashboard\IAPIWidget;
 use OCP\Dashboard\Model\WidgetItem;
 
+/**
+ * @psalm-import-type DashboardWidget from ResponseDefinitions
+ * @psalm-import-type DashboardWidgetItem from ResponseDefinitions
+ */
 class DashboardApiController extends OCSController {
 
 	/** @var IManager */
@@ -65,15 +72,15 @@ public function __construct(
 	}
 
 	/**
-	 * Example request with Curl:
-	 * curl -u user:passwd http://my.nc/ocs/v2.php/apps/dashboard/api/v1/widget-items -H Content-Type:application/json -X GET -d '{"sinceIds":{"github_notifications":"2021-03-22T15:01:10Z"}}'
+	 * @NoAdminRequired
+	 * @NoCSRFRequired
+	 *
+	 * Get the items for the widgets
 	 *
-	 * @param array $sinceIds Array indexed by widget Ids, contains date/id from which we want the new items
+	 * @param array<string, string> $sinceIds Array indexed by widget Ids, contains date/id from which we want the new items
 	 * @param int $limit Limit number of result items per widget
 	 * @param string[] $widgets Limit results to specific widgets
-	 *
-	 * @NoAdminRequired
-	 * @NoCSRFRequired
+	 * @return DataResponse<Http::STATUS_OK, array<string, DashboardWidgetItem[]>, array{}>
 	 */
 	public function getWidgetItems(array $sinceIds = [], int $limit = 7, array $widgets = []): DataResponse {
 		$showWidgets = $widgets;
@@ -97,11 +104,12 @@ public function getWidgetItems(array $sinceIds = [], int $limit = 7, array $widg
 	}
 
 	/**
-	 * Example request with Curl:
-	 * curl -u user:passwd http://my.nc/ocs/v2.php/apps/dashboard/api/v1/widgets
+	 * Get the widgets
 	 *
 	 * @NoAdminRequired
 	 * @NoCSRFRequired
+	 *
+	 * @return DataResponse<Http::STATUS_OK, DashboardWidget[], array{}>
 	 */
 	public function getWidgets(): DataResponse {
 		$widgets = $this->dashboardManager->getWidgets();

apps/dashboard/lib/Controller/DashboardController.php

@@ -9,6 +9,7 @@
  * @author Julius Härtl <[email protected]>
  * @author Morris Jobke <[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\Viewer\Event\LoadViewer;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\JSONResponse;
 use OCP\AppFramework\Http\TemplateResponse;
 use OCP\AppFramework\Services\IInitialState;
@@ -42,6 +44,7 @@
 use OCP\IConfig;
 use OCP\IRequest;
 
+#[IgnoreOpenAPI]
 class DashboardController extends Controller {
 
 	/** @var IInitialState */

apps/dashboard/lib/ResponseDefinitions.php

@@ -0,0 +1,53 @@
+<?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\Dashboard;
+
+/**
+ * @psalm-type DashboardWidget = array{
+ *     id: string,
+ *     title: string,
+ *     order: int,
+ *     icon_class: string,
+ *     icon_url: string,
+ *     widget_url: ?string,
+ *     item_icons_round: bool,
+ *     buttons?: array{
+ *         type: string,
+ *         text: string,
+ *         link: string,
+ *     }[],
+ * }
+ *
+ * @psalm-type DashboardWidgetItem = array{
+ *     subtitle: string,
+ *     title: string,
+ *     link: string,
+ *     iconUrl: string,
+ *     sinceId: string,
+ * }
+ */
+class ResponseDefinitions {
+}