dashboard: Add OpenAPI spec

Signed-off-by: jld3103 <[email protected]>

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
  *
@@ -76,6 +77,7 @@ public function __construct(
 	/**
 	 * @NoCSRFRequired
 	 * @NoAdminRequired
+	 * @IgnoreAPI
 	 * @return TemplateResponse
 	 */
 	public function index(): TemplateResponse {

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 {
+}