Skip to content

Commit 30345f8

Browse files
provokateurinprovokateurin
authored
Merge pull request #39330 from nextcloud/feature/openapi/files_sharing
files_sharing: Add OpenAPI spec
2 parents 662e73b + c680668 commit 30345f8

14 files changed

Lines changed: 942 additions & 239 deletions

‎apps/files_sharing/composer/composer/autoload_classmap.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@
7676
'OCA\\Files_Sharing\\Notification\\Listener' => $baseDir . '/../lib/Notification/Listener.php',
7777
'OCA\\Files_Sharing\\Notification\\Notifier' => $baseDir . '/../lib/Notification/Notifier.php',
7878
'OCA\\Files_Sharing\\OrphanHelper' => $baseDir . '/../lib/OrphanHelper.php',
79+
'OCA\\Files_Sharing\\ResponseDefinitions' => $baseDir . '/../lib/ResponseDefinitions.php',
7980
'OCA\\Files_Sharing\\Scanner' => $baseDir . '/../lib/Scanner.php',
8081
'OCA\\Files_Sharing\\Settings\\Personal' => $baseDir . '/../lib/Settings/Personal.php',
8182
'OCA\\Files_Sharing\\ShareBackend\\File' => $baseDir . '/../lib/ShareBackend/File.php',

‎apps/files_sharing/composer/composer/autoload_static.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@ class ComposerStaticInitFiles_Sharing
9191
'OCA\\Files_Sharing\\Notification\\Listener' => __DIR__ . '/..' . '/../lib/Notification/Listener.php',
9292
'OCA\\Files_Sharing\\Notification\\Notifier' => __DIR__ . '/..' . '/../lib/Notification/Notifier.php',
9393
'OCA\\Files_Sharing\\OrphanHelper' => __DIR__ . '/..' . '/../lib/OrphanHelper.php',
94+
'OCA\\Files_Sharing\\ResponseDefinitions' => __DIR__ . '/..' . '/../lib/ResponseDefinitions.php',
9495
'OCA\\Files_Sharing\\Scanner' => __DIR__ . '/..' . '/../lib/Scanner.php',
9596
'OCA\\Files_Sharing\\Settings\\Personal' => __DIR__ . '/..' . '/../lib/Settings/Personal.php',
9697
'OCA\\Files_Sharing\\ShareBackend\\File' => __DIR__ . '/..' . '/../lib/ShareBackend/File.php',

‎apps/files_sharing/lib/Capabilities.php‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
* @author Roeland Jago Douma <[email protected]>
99
* @author Tobias Kaminsky <[email protected]>
1010
* @author Vincent Petry <[email protected]>
11+
* @author Kate Döen <[email protected]>
1112
*
1213
* @license AGPL-3.0
1314
*
@@ -50,6 +51,67 @@ public function __construct(IConfig $config, IManager $shareManager) {
5051

5152
/**
5253
* Return this classes capabilities
54+
*
55+
* @return array{
56+
* files_sharing: array{
57+
* api_enabled: bool,
58+
* public: array{
59+
* enabled: bool,
60+
* password?: array{
61+
* enforced: bool,
62+
* askForOptionalPassword: bool
63+
* },
64+
* multiple_links?: bool,
65+
* expire_date?: array{
66+
* enabled: bool,
67+
* days?: int,
68+
* enforced?: bool,
69+
* },
70+
* expire_date_internal?: array{
71+
* enabled: bool,
72+
* days?: int,
73+
* enforced?: bool,
74+
* },
75+
* expire_date_remote?: array{
76+
* enabled: bool,
77+
* days?: int,
78+
* enforced?: bool,
79+
* },
80+
* send_mail?: bool,
81+
* upload?: bool,
82+
* upload_files_drop?: bool,
83+
* },
84+
* user: array{
85+
* send_mail: bool,
86+
* expire_date?: array{
87+
* enabled: bool,
88+
* },
89+
* },
90+
* resharing: bool,
91+
* group_sharing?: bool,
92+
* group?: array{
93+
* enabled: bool,
94+
* expire_date?: array{
95+
* enabled: bool,
96+
* },
97+
* },
98+
* default_permissions?: int,
99+
* federation: array{
100+
* outgoing: bool,
101+
* incoming: bool,
102+
* expire_date: array{
103+
* enabled: bool,
104+
* },
105+
* expire_date_supported: array{
106+
* enabled: bool,
107+
* },
108+
* },
109+
* sharee: array{
110+
* query_lookup_default: bool,
111+
* always_show_unique: bool,
112+
* },
113+
* },
114+
* }
53115
*/
54116
public function getCapabilities() {
55117
$res = [];

‎apps/files_sharing/lib/Controller/AcceptController.php‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
* @copyright Copyright (c) 2020, Roeland Jago Douma <[email protected]>
77
*
88
* @author Roeland Jago Douma <[email protected]>
9+
* @author Kate Döen <[email protected]>
910
*
1011
* @license GNU AGPL version 3 or any later version
1112
*
@@ -27,6 +28,7 @@
2728

2829
use OCA\Files_Sharing\AppInfo\Application;
2930
use OCP\AppFramework\Controller;
31+
use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
3032
use OCP\AppFramework\Http\NotFoundResponse;
3133
use OCP\AppFramework\Http\RedirectResponse;
3234
use OCP\AppFramework\Http\Response;
@@ -36,6 +38,7 @@
3638
use OCP\Share\Exceptions\ShareNotFound;
3739
use OCP\Share\IManager as ShareManager;
3840

41+
#[IgnoreOpenAPI]
3942
class AcceptController extends Controller {
4043

4144
/** @var ShareManager */

‎apps/files_sharing/lib/Controller/DeletedShareAPIController.php‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
* @author John Molakvoæ <[email protected]>
1212
* @author Julius Härtl <[email protected]>
1313
* @author Roeland Jago Douma <[email protected]>
14+
* @author Kate Döen <[email protected]>
1415
*
1516
* @license GNU AGPL version 3 or any later version
1617
*
@@ -30,7 +31,9 @@
3031
*/
3132
namespace OCA\Files_Sharing\Controller;
3233

34+
use OCA\Files_Sharing\ResponseDefinitions;
3335
use OCP\App\IAppManager;
36+
use OCP\AppFramework\Http;
3437
use OCP\AppFramework\Http\DataResponse;
3538
use OCP\AppFramework\OCS\OCSException;
3639
use OCP\AppFramework\OCS\OCSNotFoundException;
@@ -47,6 +50,9 @@
4750
use OCP\Share\IManager as ShareManager;
4851
use OCP\Share\IShare;
4952

53+
/**
54+
* @psalm-import-type FilesSharingDeletedShare from ResponseDefinitions
55+
*/
5056
class DeletedShareAPIController extends OCSController {
5157

5258
/** @var ShareManager */
@@ -92,6 +98,8 @@ public function __construct(string $appName,
9298

9399
/**
94100
* @suppress PhanUndeclaredClassMethod
101+
*
102+
* @return FilesSharingDeletedShare
95103
*/
96104
private function formatShare(IShare $share): array {
97105
$result = [
@@ -176,6 +184,10 @@ private function formatShare(IShare $share): array {
176184

177185
/**
178186
* @NoAdminRequired
187+
*
188+
* Get a list of all deleted shares
189+
*
190+
* @return DataResponse<Http::STATUS_OK, FilesSharingDeletedShare[], array{}>
179191
*/
180192
public function index(): DataResponse {
181193
$groupShares = $this->shareManager->getDeletedSharedWith($this->userId, IShare::TYPE_GROUP, null, -1, 0);
@@ -195,7 +207,14 @@ public function index(): DataResponse {
195207
/**
196208
* @NoAdminRequired
197209
*
210+
* Undelete a deleted share
211+
*
212+
* @param string $id ID of the share
213+
* @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
198214
* @throws OCSException
215+
* @throws OCSNotFoundException Share not found
216+
*
217+
* 200: Share undeleted successfully
199218
*/
200219
public function undelete(string $id): DataResponse {
201220
try {

‎apps/files_sharing/lib/Controller/PublicPreviewController.php‎

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
* @author Julius Härtl <[email protected]>
66
* @author Morris Jobke <[email protected]>
77
* @author Roeland Jago Douma <[email protected]>
8+
* @author Kate Döen <[email protected]>
89
*
910
* @license GNU AGPL version 3 or any later version
1011
*
@@ -82,11 +83,19 @@ protected function isPasswordProtected(): bool {
8283
* @PublicPage
8384
* @NoCSRFRequired
8485
*
85-
* @param string $file
86-
* @param int $x
87-
* @param int $y
88-
* @param bool $a
89-
* @return DataResponse|FileDisplayResponse
86+
* Get a preview for a shared file
87+
*
88+
* @param string $token Token of the share
89+
* @param string $file File in the share
90+
* @param int $x Width of the preview
91+
* @param int $y Height of the preview
92+
* @param bool $a Whether to not crop the preview
93+
* @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>
94+
*
95+
* 200: Preview returned
96+
* 400: Getting preview is not possible
97+
* 403: Getting preview is not allowed
98+
* 404: Share or preview not found
9099
*/
91100
public function getPreview(
92101
string $token,
@@ -138,8 +147,15 @@ public function getPreview(
138147
* @NoCSRFRequired
139148
* @NoSameSiteCookieRequired
140149
*
141-
* @param $token
142-
* @return DataResponse|FileDisplayResponse
150+
* Get a direct link preview for a shared file
151+
*
152+
* @param string $token Token of the share
153+
* @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>
154+
*
155+
* 200: Preview returned
156+
* 400: Getting preview is not possible
157+
* 403: Getting preview is not allowed
158+
* 404: Share or preview not found
143159
*/
144160
public function directLink(string $token) {
145161
// No token no image

‎apps/files_sharing/lib/Controller/RemoteController.php‎

Lines changed: 30 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
* @author Bjoern Schiessle <[email protected]>
66
* @author Joas Schilling <[email protected]>
77
* @author Roeland Jago Douma <[email protected]>
8+
* @author Kate Döen <[email protected]>
89
*
910
* @license AGPL-3.0
1011
*
@@ -24,13 +25,18 @@
2425
namespace OCA\Files_Sharing\Controller;
2526

2627
use OCA\Files_Sharing\External\Manager;
28+
use OCA\Files_Sharing\ResponseDefinitions;
29+
use OCP\AppFramework\Http;
2730
use OCP\AppFramework\Http\DataResponse;
2831
use OCP\AppFramework\OCS\OCSForbiddenException;
2932
use OCP\AppFramework\OCS\OCSNotFoundException;
3033
use OCP\AppFramework\OCSController;
3134
use OCP\IRequest;
3235
use Psr\Log\LoggerInterface;
3336

37+
/**
38+
* @psalm-import-type FilesSharingRemoteShare from ResponseDefinitions
39+
*/
3440
class RemoteController extends OCSController {
3541
/**
3642
* @NoAdminRequired
@@ -55,7 +61,7 @@ public function __construct(
5561
*
5662
* Get list of pending remote shares
5763
*
58-
* @return DataResponse
64+
* @return DataResponse<Http::STATUS_OK, FilesSharingRemoteShare[], array{}>
5965
*/
6066
public function getOpenShares() {
6167
return new DataResponse($this->externalManager->getOpenShares());
@@ -66,9 +72,11 @@ public function getOpenShares() {
6672
*
6773
* Accept a remote share
6874
*
69-
* @param int $id
70-
* @return DataResponse
71-
* @throws OCSNotFoundException
75+
* @param int $id ID of the share
76+
* @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
77+
* @throws OCSNotFoundException Share not found
78+
*
79+
* 200: Share accepted successfully
7280
*/
7381
public function acceptShare($id) {
7482
if ($this->externalManager->acceptShare($id)) {
@@ -86,9 +94,11 @@ public function acceptShare($id) {
8694
*
8795
* Decline a remote share
8896
*
89-
* @param int $id
90-
* @return DataResponse
91-
* @throws OCSNotFoundException
97+
* @param int $id ID of the share
98+
* @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
99+
* @throws OCSNotFoundException Share not found
100+
*
101+
* 200: Share declined successfully
92102
*/
93103
public function declineShare($id) {
94104
if ($this->externalManager->declineShare($id)) {
@@ -125,9 +135,9 @@ private static function extendShareInfo($share) {
125135
/**
126136
* @NoAdminRequired
127137
*
128-
* List accepted remote shares
138+
* Get a list of accepted remote shares
129139
*
130-
* @return DataResponse
140+
* @return DataResponse<Http::STATUS_OK, FilesSharingRemoteShare[], array{}>
131141
*/
132142
public function getShares() {
133143
$shares = $this->externalManager->getAcceptedShares();
@@ -141,9 +151,11 @@ public function getShares() {
141151
*
142152
* Get info of a remote share
143153
*
144-
* @param int $id
145-
* @return DataResponse
146-
* @throws OCSNotFoundException
154+
* @param int $id ID of the share
155+
* @return DataResponse<Http::STATUS_OK, FilesSharingRemoteShare, array{}>
156+
* @throws OCSNotFoundException Share not found
157+
*
158+
* 200: Share returned
147159
*/
148160
public function getShare($id) {
149161
$shareInfo = $this->externalManager->getShare($id);
@@ -161,10 +173,12 @@ public function getShare($id) {
161173
*
162174
* Unshare a remote share
163175
*
164-
* @param int $id
165-
* @return DataResponse
166-
* @throws OCSNotFoundException
167-
* @throws OCSForbiddenException
176+
* @param int $id ID of the share
177+
* @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
178+
* @throws OCSNotFoundException Share not found
179+
* @throws OCSForbiddenException Unsharing is not possible
180+
*
181+
* 200: Share unshared successfully
168182
*/
169183
public function unshare($id) {
170184
$shareInfo = $this->externalManager->getShare($id);

0 commit comments

Comments
 (0)