Skip to content

Commit 4991d2e

Browse files
provokateurinprovokateurin
authored
Merge pull request #39328 from nextcloud/feature/openapi/federatedfilesharing
federatedfilesharing: Add OpenAPI spec
2 parents 402338c + 4ead6e6 commit 4991d2e

File tree

6 files changed

+1021
-58
lines changed

6 files changed

+1021
-58
lines changed

‎apps/federatedfilesharing/lib/AddressHandler.php

+1-1
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ public function __construct(
6767
* split user and remote from federated cloud id
6868
*
6969
* @param string $address federated share address
70-
* @return array [user, remoteURL]
70+
* @return array<string> [user, remoteURL]
7171
* @throws HintException
7272
*/
7373
public function splitUserRemote($address) {

‎apps/federatedfilesharing/lib/Controller/MountPublicLinkController.php

+6-4
Original file line numberDiff line numberDiff line change
@@ -82,10 +82,12 @@ public function __construct(
8282
* @PublicPage
8383
* @BruteForceProtection(action=publicLink2FederatedShare)
8484
*
85-
* @param string $shareWith
86-
* @param string $token
87-
* @param string $password
88-
* @return JSONResponse
85+
* @param string $shareWith Username to share with
86+
* @param string $token Token of the share
87+
* @param string $password Password of the share
88+
* @return JSONResponse<Http::STATUS_OK, array{remoteUrl: string}, array{}>|JSONResponse<Http::STATUS_BAD_REQUEST, array{message: string}, array{}>
89+
* 200: Remote URL returned
90+
* 400: Creating share is not possible
8991
*/
9092
public function createFederatedShare($shareWith, $token, $password = '') {
9193
if (!$this->federatedShareProvider->isOutgoingServer2serverShareEnabled()) {

‎apps/federatedfilesharing/lib/Controller/RequestHandlerController.php

+51-45
Original file line numberDiff line numberDiff line change
@@ -123,16 +123,16 @@ public function __construct(string $appName,
123123
*
124124
* create a new share
125125
*
126-
* @param string|null $remote
127-
* @param string|null $token
128-
* @param string|null $name
129-
* @param string|null $owner
130-
* @param string|null $sharedBy
131-
* @param string|null $shareWith
132-
* @param int|null $remoteId
133-
* @param string|null $sharedByFederatedId
134-
* @param string|null $ownerFederatedId
135-
* @return Http\DataResponse
126+
* @param string|null $remote Address of the remote
127+
* @param string|null $token Shared secret between servers
128+
* @param string|null $name Name of the shared resource
129+
* @param string|null $owner Display name of the receiver
130+
* @param string|null $sharedBy Display name of the sender
131+
* @param string|null $shareWith ID of the user that receives the share
132+
* @param int|null $remoteId ID of the remote
133+
* @param string|null $sharedByFederatedId Federated ID of the sender
134+
* @param string|null $ownerFederatedId Federated ID of the receiver
135+
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
136136
* @throws OCSException
137137
*/
138138
public function createShare(
@@ -194,19 +194,19 @@ public function createShare(
194194
*
195195
* create re-share on behalf of another user
196196
*
197-
* @param int $id
198-
* @param string|null $token
199-
* @param string|null $shareWith
200-
* @param int|null $permission
201-
* @param int|null $remoteId
202-
* @return Http\DataResponse
203-
* @throws OCSBadRequestException
197+
* @param int $id ID of the share
198+
* @param string|null $token Shared secret between servers
199+
* @param string|null $shareWith ID of the user that receives the share
200+
* @param int|null $remoteId ID of the remote
201+
* @return Http\DataResponse<Http::STATUS_OK, array{token: string, remoteId: string}, array{}>
202+
* @throws OCSBadRequestException Re-sharing is not possible
204203
* @throws OCSException
204+
*
205+
* 200: Remote share returned
205206
*/
206-
public function reShare(int $id, ?string $token = null, ?string $shareWith = null, ?int $permission = 0, ?int $remoteId = 0) {
207+
public function reShare(int $id, ?string $token = null, ?string $shareWith = null, ?int $remoteId = 0) {
207208
if ($token === null ||
208209
$shareWith === null ||
209-
$permission === null ||
210210
$remoteId === null
211211
) {
212212
throw new OCSBadRequestException();
@@ -244,12 +244,14 @@ public function reShare(int $id, ?string $token = null, ?string $shareWith = nul
244244
*
245245
* accept server-to-server share
246246
*
247-
* @param int $id
248-
* @param string|null $token
249-
* @return Http\DataResponse
247+
* @param int $id ID of the remote share
248+
* @param string|null $token Shared secret between servers
249+
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
250250
* @throws OCSException
251251
* @throws ShareNotFound
252252
* @throws \OCP\HintException
253+
*
254+
* 200: Share accepted successfully
253255
*/
254256
public function acceptShare(int $id, ?string $token = null) {
255257
$notification = [
@@ -278,9 +280,9 @@ public function acceptShare(int $id, ?string $token = null) {
278280
*
279281
* decline server-to-server share
280282
*
281-
* @param int $id
282-
* @param string|null $token
283-
* @return Http\DataResponse
283+
* @param int $id ID of the remote share
284+
* @param string|null $token Shared secret between servers
285+
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
284286
* @throws OCSException
285287
*/
286288
public function declineShare(int $id, ?string $token = null) {
@@ -310,9 +312,9 @@ public function declineShare(int $id, ?string $token = null) {
310312
*
311313
* remove server-to-server share if it was unshared by the owner
312314
*
313-
* @param int $id
314-
* @param string|null $token
315-
* @return Http\DataResponse
315+
* @param int $id ID of the share
316+
* @param string|null $token Shared secret between servers
317+
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
316318
* @throws OCSException
317319
*/
318320
public function unshare(int $id, ?string $token = null) {
@@ -345,10 +347,12 @@ private function cleanupRemote($remote) {
345347
*
346348
* federated share was revoked, either by the owner or the re-sharer
347349
*
348-
* @param int $id
349-
* @param string|null $token
350-
* @return Http\DataResponse
351-
* @throws OCSBadRequestException
350+
* @param int $id ID of the share
351+
* @param string|null $token Shared secret between servers
352+
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
353+
* @throws OCSBadRequestException Revoking the share is not possible
354+
*
355+
* 200: Share revoked successfully
352356
*/
353357
public function revoke(int $id, ?string $token = null) {
354358
try {
@@ -385,11 +389,13 @@ private function isS2SEnabled($incoming = false) {
385389
*
386390
* update share information to keep federated re-shares in sync
387391
*
388-
* @param int $id
389-
* @param string|null $token
390-
* @param int|null $permissions
391-
* @return Http\DataResponse
392-
* @throws OCSBadRequestException
392+
* @param int $id ID of the share
393+
* @param string|null $token Shared secret between servers
394+
* @param int|null $permissions New permissions
395+
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
396+
* @throws OCSBadRequestException Updating permissions is not possible
397+
*
398+
* 200: Permissions updated successfully
393399
*/
394400
public function updatePermissions(int $id, ?string $token = null, ?int $permissions = null) {
395401
$ncPermissions = $permissions;
@@ -439,14 +445,14 @@ protected function ncPermissions2ocmPermissions($ncPermissions) {
439445
*
440446
* change the owner of a server-to-server share
441447
*
442-
* @param int $id
443-
* @param string|null $token
444-
* @param string|null $remote
445-
* @param string|null $remote_id
446-
* @return Http\DataResponse
447-
* @throws OCSBadRequestException
448-
* @throws OCSException
449-
* @throws \OCP\DB\Exception
448+
* @param int $id ID of the share
449+
* @param string|null $token Shared secret between servers
450+
* @param string|null $remote Address of the remote
451+
* @param string|null $remote_id ID of the remote
452+
* @return Http\DataResponse<Http::STATUS_OK, array{remote: string, owner: string}, array{}>
453+
* @throws OCSBadRequestException Moving share is not possible
454+
*
455+
* 200: Share moved successfully
450456
*/
451457
public function move(int $id, ?string $token = null, ?string $remote = null, ?string $remote_id = null) {
452458
if (!$this->isS2SEnabled()) {

‎apps/federatedfilesharing/lib/OCM/CloudFederationProviderFiles.php

+7-7
Original file line numberDiff line numberDiff line change
@@ -211,7 +211,7 @@ public function shareReceived(ICloudFederationShare $share) {
211211
* @param string $notificationType (e.g. SHARE_ACCEPTED)
212212
* @param string $providerId id of the share
213213
* @param array $notification payload of the notification
214-
* @return array data send back to the sender
214+
* @return array<string> data send back to the sender
215215
*
216216
* @throws ActionNotSupportedException
217217
* @throws AuthenticationFailedException
@@ -280,7 +280,7 @@ private function notifyAboutNewShare($shareWith, $shareId, $ownerFederatedId, $s
280280
*
281281
* @param string $id
282282
* @param array $notification
283-
* @return array
283+
* @return array<string>
284284
* @throws ActionNotSupportedException
285285
* @throws AuthenticationFailedException
286286
* @throws BadRequestException
@@ -348,7 +348,7 @@ protected function executeAcceptShare(IShare $share) {
348348
*
349349
* @param string $id
350350
* @param array $notification
351-
* @return array
351+
* @return array<string>
352352
* @throws ActionNotSupportedException
353353
* @throws AuthenticationFailedException
354354
* @throws BadRequestException
@@ -424,7 +424,7 @@ protected function executeDeclineShare(IShare $share) {
424424
*
425425
* @param string $id
426426
* @param array $notification
427-
* @return array
427+
* @return array<string>
428428
* @throws AuthenticationFailedException
429429
* @throws BadRequestException
430430
*/
@@ -446,7 +446,7 @@ private function undoReshare($id, array $notification) {
446446
*
447447
* @param string $id
448448
* @param array $notification
449-
* @return array
449+
* @return array<string>
450450
* @throws ActionNotSupportedException
451451
* @throws BadRequestException
452452
*/
@@ -536,7 +536,7 @@ private function cleanupRemote($remote) {
536536
*
537537
* @param string $id
538538
* @param array $notification
539-
* @return array
539+
* @return array<string>
540540
* @throws AuthenticationFailedException
541541
* @throws BadRequestException
542542
* @throws ProviderCouldNotAddShareException
@@ -597,7 +597,7 @@ protected function reshareRequested($id, array $notification) {
597597
*
598598
* @param string $id
599599
* @param array $notification
600-
* @return array
600+
* @return array<string>
601601
* @throws AuthenticationFailedException
602602
* @throws BadRequestException
603603
*/

0 commit comments

Comments
 (0)