diff --git a/apps/dashboard/composer/composer/autoload_classmap.php b/apps/dashboard/composer/composer/autoload_classmap.php index 99072b8f2899b..b52e81f8c4282 100644 --- a/apps/dashboard/composer/composer/autoload_classmap.php +++ b/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', ); diff --git a/apps/dashboard/composer/composer/autoload_static.php b/apps/dashboard/composer/composer/autoload_static.php index 63a4f6b67d4ea..6dbd68c9a1213 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 1062cf1bdba02..df1c75e4b6883 100644 --- a/apps/dashboard/lib/Controller/DashboardApiController.php +++ b/apps/dashboard/lib/Controller/DashboardApiController.php @@ -6,6 +6,7 @@ * @copyright Copyright (c) 2021 Julien Veyssier * * @author Julien Veyssier + * @author Kate Döen * * @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 $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, 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 */ 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 b0e150e00f7eb..e72fde4b7bd02 100644 --- a/apps/dashboard/lib/Controller/DashboardController.php +++ b/apps/dashboard/lib/Controller/DashboardController.php @@ -9,6 +9,7 @@ * @author Julius Härtl * @author Morris Jobke * @author Roeland Jago Douma + * @author Kate Döen * * @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 */ diff --git a/apps/dashboard/lib/ResponseDefinitions.php b/apps/dashboard/lib/ResponseDefinitions.php new file mode 100644 index 0000000000000..1c40f251f2a57 --- /dev/null +++ b/apps/dashboard/lib/ResponseDefinitions.php @@ -0,0 +1,53 @@ + + * + * @author Kate Döen + * + * @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 . + * + */ + +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 { +}