dashboard: Add OpenAPI spec

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

5 files changed, 74 insertions, 8 deletions

diff --git a/apps/dashboard/composer/composer/autoload_classmap.php b/apps/dashboard/composer/composer/autoload_classmap.php
index 99072b8f289..b52e81f8c42 100644
--- a/apps/dashboard/composer/composer/autoload_classmap.php
+++ b/apps/dashboard/composer/composer/autoload_classmap.php
@@ -10,4 +10,5 @@ return array(
     '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',
 );
diff --git a/apps/dashboard/composer/composer/autoload_static.php b/apps/dashboard/composer/composer/autoload_static.php
index 63a4f6b67d4..6dbd68c9a12 100644
--- a/apps/dashboard/composer/composer/autoload_static.php
+++ b/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)
diff --git a/apps/dashboard/lib/Controller/DashboardApiController.php b/apps/dashboard/lib/Controller/DashboardApiController.php
index 1062cf1bdba..df1c75e4b68 100644
--- a/apps/dashboard/lib/Controller/DashboardApiController.php
+++ b/apps/dashboard/lib/Controller/DashboardApiController.php
@@ -6,6 +6,7 @@ declare(strict_types=1);
  * @copyright Copyright (c) 2021 Julien Veyssier <eneiluj@posteo.net>
  *
  * @author Julien Veyssier <eneiluj@posteo.net>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -26,7 +27,9 @@ declare(strict_types=1);
 
 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\IRequest;
 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 @@ class DashboardApiController extends OCSController {
 	}
 
 	/**
-	 * 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 @@ class DashboardApiController extends OCSController {
 	}
 
 	/**
-	 * 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();
diff --git a/apps/dashboard/lib/Controller/DashboardController.php b/apps/dashboard/lib/Controller/DashboardController.php
index b0e150e00f7..e72fde4b7bd 100644
--- a/apps/dashboard/lib/Controller/DashboardController.php
+++ b/apps/dashboard/lib/Controller/DashboardController.php
@@ -9,6 +9,7 @@ declare(strict_types=1);
  * @author Julius Härtl <jus@bitgrid.net>
  * @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
  *
@@ -32,6 +33,7 @@ use OCA\Files\Event\LoadSidebar;
 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\EventDispatcher\IEventDispatcher;
 use OCP\IConfig;
 use OCP\IRequest;
 
+#[IgnoreOpenAPI]
 class DashboardController extends Controller {
 
 	/** @var IInitialState */
diff --git a/apps/dashboard/lib/ResponseDefinitions.php b/apps/dashboard/lib/ResponseDefinitions.php
new file mode 100644
index 00000000000..1c40f251f2a
--- /dev/null
+++ b/apps/dashboard/lib/ResponseDefinitions.php
@@ -0,0 +1,53 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Kate Döen <kate.doeen@nextcloud.com>
+ *
+ * @author Kate Döen <kate.doeen@nextcloud.com>
+ *
+ * @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 {
+}