From f8bed12cfb01d95d92098c0e957cae9c22ec484a Mon Sep 17 00:00:00 2001 From: jld3103 Date: Mon, 20 Mar 2023 18:13:24 +0100 Subject: [PATCH] dashboard: Add OpenAPI spec Signed-off-by: jld3103 --- .../composer/composer/autoload_classmap.php | 1 + .../composer/composer/autoload_static.php | 1 + .../lib/Controller/DashboardApiController.php | 24 ++++++--- .../lib/Controller/DashboardController.php | 3 ++ apps/dashboard/lib/ResponseDefinitions.php | 53 +++++++++++++++++++ 5 files changed, 74 insertions(+), 8 deletions(-) create mode 100644 apps/dashboard/lib/ResponseDefinitions.php 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 * * @author Julien Veyssier + * @author Kate Döen * * @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 $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 @@ 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 */ 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 * @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\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 @@ + + * + * @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 { +} -- 2.39.5