upstream/nextcloud
1
0
Fork 0
mirror of https://github.com/nextcloud/server.git synced 2026-05-28 04:32:30 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 54

Merge pull request #39286 from nextcloud/feature/openapi/dashboard

Browse source 
dashboard: Add OpenAPI spec
This commit is contained in:
Kate 2023-07-11 10:57:14 +02:00 committed by GitHub
commit 5661fe9719
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 75 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
apps/dashboard/composer/composer/autoload_classmap.php
View file

@ -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',
);

1
apps/dashboard/composer/composer/autoload_static.php
View file

@ -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)

26
apps/dashboard/lib/Controller/DashboardApiController.php
View file

@ -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"}}'
*
* @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
*
* Get the items for the widgets
*
* @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
* @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();

3
apps/dashboard/lib/Controller/DashboardController.php
View file

@ -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 */

53
apps/dashboard/lib/ResponseDefinitions.php Normal file
View file

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