From: jld3103 Date: Wed, 14 Jun 2023 07:44:03 +0000 (+0200) Subject: federatedfilesharing: Add OpenAPI spec X-Git-Tag: v28.0.0beta1~717^2 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=refs%2Fpull%2F39328%2Fhead;p=nextcloud-server.git federatedfilesharing: Add OpenAPI spec Signed-off-by: jld3103 --- diff --git a/apps/federatedfilesharing/lib/AddressHandler.php b/apps/federatedfilesharing/lib/AddressHandler.php index d76ff9518b6..66af86b9159 100644 --- a/apps/federatedfilesharing/lib/AddressHandler.php +++ b/apps/federatedfilesharing/lib/AddressHandler.php @@ -67,7 +67,7 @@ class AddressHandler { * split user and remote from federated cloud id * * @param string $address federated share address - * @return array [user, remoteURL] + * @return array [user, remoteURL] * @throws HintException */ public function splitUserRemote($address) { diff --git a/apps/federatedfilesharing/lib/Controller/MountPublicLinkController.php b/apps/federatedfilesharing/lib/Controller/MountPublicLinkController.php index 7042715b70c..f13a77d9368 100644 --- a/apps/federatedfilesharing/lib/Controller/MountPublicLinkController.php +++ b/apps/federatedfilesharing/lib/Controller/MountPublicLinkController.php @@ -82,10 +82,12 @@ class MountPublicLinkController extends Controller { * @PublicPage * @BruteForceProtection(action=publicLink2FederatedShare) * - * @param string $shareWith - * @param string $token - * @param string $password - * @return JSONResponse + * @param string $shareWith Username to share with + * @param string $token Token of the share + * @param string $password Password of the share + * @return JSONResponse|JSONResponse + * 200: Remote URL returned + * 400: Creating share is not possible */ public function createFederatedShare($shareWith, $token, $password = '') { if (!$this->federatedShareProvider->isOutgoingServer2serverShareEnabled()) { diff --git a/apps/federatedfilesharing/lib/Controller/RequestHandlerController.php b/apps/federatedfilesharing/lib/Controller/RequestHandlerController.php index 2dd8098b3b0..59e46af37cd 100644 --- a/apps/federatedfilesharing/lib/Controller/RequestHandlerController.php +++ b/apps/federatedfilesharing/lib/Controller/RequestHandlerController.php @@ -123,16 +123,16 @@ class RequestHandlerController extends OCSController { * * create a new share * - * @param string|null $remote - * @param string|null $token - * @param string|null $name - * @param string|null $owner - * @param string|null $sharedBy - * @param string|null $shareWith - * @param int|null $remoteId - * @param string|null $sharedByFederatedId - * @param string|null $ownerFederatedId - * @return Http\DataResponse + * @param string|null $remote Address of the remote + * @param string|null $token Shared secret between servers + * @param string|null $name Name of the shared resource + * @param string|null $owner Display name of the receiver + * @param string|null $sharedBy Display name of the sender + * @param string|null $shareWith ID of the user that receives the share + * @param int|null $remoteId ID of the remote + * @param string|null $sharedByFederatedId Federated ID of the sender + * @param string|null $ownerFederatedId Federated ID of the receiver + * @return Http\DataResponse, array{}> * @throws OCSException */ public function createShare( @@ -194,19 +194,19 @@ class RequestHandlerController extends OCSController { * * create re-share on behalf of another user * - * @param int $id - * @param string|null $token - * @param string|null $shareWith - * @param int|null $permission - * @param int|null $remoteId - * @return Http\DataResponse - * @throws OCSBadRequestException + * @param int $id ID of the share + * @param string|null $token Shared secret between servers + * @param string|null $shareWith ID of the user that receives the share + * @param int|null $remoteId ID of the remote + * @return Http\DataResponse + * @throws OCSBadRequestException Re-sharing is not possible * @throws OCSException + * + * 200: Remote share returned */ - public function reShare(int $id, ?string $token = null, ?string $shareWith = null, ?int $permission = 0, ?int $remoteId = 0) { + public function reShare(int $id, ?string $token = null, ?string $shareWith = null, ?int $remoteId = 0) { if ($token === null || $shareWith === null || - $permission === null || $remoteId === null ) { throw new OCSBadRequestException(); @@ -244,12 +244,14 @@ class RequestHandlerController extends OCSController { * * accept server-to-server share * - * @param int $id - * @param string|null $token - * @return Http\DataResponse + * @param int $id ID of the remote share + * @param string|null $token Shared secret between servers + * @return Http\DataResponse, array{}> * @throws OCSException * @throws ShareNotFound * @throws \OCP\HintException + * + * 200: Share accepted successfully */ public function acceptShare(int $id, ?string $token = null) { $notification = [ @@ -278,9 +280,9 @@ class RequestHandlerController extends OCSController { * * decline server-to-server share * - * @param int $id - * @param string|null $token - * @return Http\DataResponse + * @param int $id ID of the remote share + * @param string|null $token Shared secret between servers + * @return Http\DataResponse, array{}> * @throws OCSException */ public function declineShare(int $id, ?string $token = null) { @@ -310,9 +312,9 @@ class RequestHandlerController extends OCSController { * * remove server-to-server share if it was unshared by the owner * - * @param int $id - * @param string|null $token - * @return Http\DataResponse + * @param int $id ID of the share + * @param string|null $token Shared secret between servers + * @return Http\DataResponse, array{}> * @throws OCSException */ public function unshare(int $id, ?string $token = null) { @@ -345,10 +347,12 @@ class RequestHandlerController extends OCSController { * * federated share was revoked, either by the owner or the re-sharer * - * @param int $id - * @param string|null $token - * @return Http\DataResponse - * @throws OCSBadRequestException + * @param int $id ID of the share + * @param string|null $token Shared secret between servers + * @return Http\DataResponse, array{}> + * @throws OCSBadRequestException Revoking the share is not possible + * + * 200: Share revoked successfully */ public function revoke(int $id, ?string $token = null) { try { @@ -385,11 +389,13 @@ class RequestHandlerController extends OCSController { * * update share information to keep federated re-shares in sync * - * @param int $id - * @param string|null $token - * @param int|null $permissions - * @return Http\DataResponse - * @throws OCSBadRequestException + * @param int $id ID of the share + * @param string|null $token Shared secret between servers + * @param int|null $permissions New permissions + * @return Http\DataResponse, array{}> + * @throws OCSBadRequestException Updating permissions is not possible + * + * 200: Permissions updated successfully */ public function updatePermissions(int $id, ?string $token = null, ?int $permissions = null) { $ncPermissions = $permissions; @@ -439,14 +445,14 @@ class RequestHandlerController extends OCSController { * * change the owner of a server-to-server share * - * @param int $id - * @param string|null $token - * @param string|null $remote - * @param string|null $remote_id - * @return Http\DataResponse - * @throws OCSBadRequestException - * @throws OCSException - * @throws \OCP\DB\Exception + * @param int $id ID of the share + * @param string|null $token Shared secret between servers + * @param string|null $remote Address of the remote + * @param string|null $remote_id ID of the remote + * @return Http\DataResponse + * @throws OCSBadRequestException Moving share is not possible + * + * 200: Share moved successfully */ public function move(int $id, ?string $token = null, ?string $remote = null, ?string $remote_id = null) { if (!$this->isS2SEnabled()) { diff --git a/apps/federatedfilesharing/lib/OCM/CloudFederationProviderFiles.php b/apps/federatedfilesharing/lib/OCM/CloudFederationProviderFiles.php index 6ae334f1991..5d6a11c2ffd 100644 --- a/apps/federatedfilesharing/lib/OCM/CloudFederationProviderFiles.php +++ b/apps/federatedfilesharing/lib/OCM/CloudFederationProviderFiles.php @@ -211,7 +211,7 @@ class CloudFederationProviderFiles implements ICloudFederationProvider { * @param string $notificationType (e.g. SHARE_ACCEPTED) * @param string $providerId id of the share * @param array $notification payload of the notification - * @return array data send back to the sender + * @return array data send back to the sender * * @throws ActionNotSupportedException * @throws AuthenticationFailedException @@ -280,7 +280,7 @@ class CloudFederationProviderFiles implements ICloudFederationProvider { * * @param string $id * @param array $notification - * @return array + * @return array * @throws ActionNotSupportedException * @throws AuthenticationFailedException * @throws BadRequestException @@ -348,7 +348,7 @@ class CloudFederationProviderFiles implements ICloudFederationProvider { * * @param string $id * @param array $notification - * @return array + * @return array * @throws ActionNotSupportedException * @throws AuthenticationFailedException * @throws BadRequestException @@ -424,7 +424,7 @@ class CloudFederationProviderFiles implements ICloudFederationProvider { * * @param string $id * @param array $notification - * @return array + * @return array * @throws AuthenticationFailedException * @throws BadRequestException */ @@ -446,7 +446,7 @@ class CloudFederationProviderFiles implements ICloudFederationProvider { * * @param string $id * @param array $notification - * @return array + * @return array * @throws ActionNotSupportedException * @throws BadRequestException */ @@ -536,7 +536,7 @@ class CloudFederationProviderFiles implements ICloudFederationProvider { * * @param string $id * @param array $notification - * @return array + * @return array * @throws AuthenticationFailedException * @throws BadRequestException * @throws ProviderCouldNotAddShareException @@ -597,7 +597,7 @@ class CloudFederationProviderFiles implements ICloudFederationProvider { * * @param string $id * @param array $notification - * @return array + * @return array * @throws AuthenticationFailedException * @throws BadRequestException */ diff --git a/apps/federatedfilesharing/openapi.json b/apps/federatedfilesharing/openapi.json new file mode 100644 index 00000000000..0bbe535cc2a --- /dev/null +++ b/apps/federatedfilesharing/openapi.json @@ -0,0 +1,955 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "federatedfilesharing", + "version": "0.0.1", + "description": "Provide federated file sharing across servers", + "license": { + "name": "agpl" + } + }, + "components": { + "securitySchemes": { + "basic_auth": { + "type": "http", + "scheme": "basic" + }, + "bearer_auth": { + "type": "http", + "scheme": "bearer" + } + }, + "schemas": { + "OCSMeta": { + "type": "object", + "required": [ + "status", + "statuscode" + ], + "properties": { + "status": { + "type": "string" + }, + "statuscode": { + "type": "integer" + }, + "message": { + "type": "string" + }, + "totalitems": { + "type": "string" + }, + "itemsperpage": { + "type": "string" + } + } + } + } + }, + "paths": { + "/index.php/apps/federatedfilesharing/createFederatedShare": { + "post": { + "operationId": "mount_public_link-create-federated-share", + "summary": "send federated share to a user of a public link", + "tags": [ + "mount_public_link" + ], + "security": [ + {}, + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "shareWith", + "in": "query", + "description": "Username to share with", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "token", + "in": "query", + "description": "Token of the share", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "password", + "in": "query", + "description": "Password of the share", + "schema": { + "type": "string", + "default": "" + } + } + ], + "responses": { + "200": { + "description": "Remote URL returned", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "remoteUrl" + ], + "properties": { + "remoteUrl": { + "type": "string" + } + } + } + } + } + }, + "400": { + "description": "Creating share is not possible", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "message" + ], + "properties": { + "message": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/cloud/shares": { + "post": { + "operationId": "request_handler-create-share", + "summary": "create a new share", + "tags": [ + "request_handler" + ], + "security": [ + {}, + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "remote", + "in": "query", + "description": "Address of the remote", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "token", + "in": "query", + "description": "Shared secret between servers", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "name", + "in": "query", + "description": "Name of the shared resource", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "owner", + "in": "query", + "description": "Display name of the receiver", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "sharedBy", + "in": "query", + "description": "Display name of the sender", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "shareWith", + "in": "query", + "description": "ID of the user that receives the share", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "remoteId", + "in": "query", + "description": "ID of the remote", + "schema": { + "type": "integer", + "format": "int64", + "nullable": true + } + }, + { + "name": "sharedByFederatedId", + "in": "query", + "description": "Federated ID of the sender", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "ownerFederatedId", + "in": "query", + "description": "Federated ID of the receiver", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/cloud/shares/{id}/reshare": { + "post": { + "operationId": "request_handler-re-share", + "summary": "create re-share on behalf of another user", + "tags": [ + "request_handler" + ], + "security": [ + {}, + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "token", + "in": "query", + "description": "Shared secret between servers", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "shareWith", + "in": "query", + "description": "ID of the user that receives the share", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "remoteId", + "in": "query", + "description": "ID of the remote", + "schema": { + "type": "integer", + "format": "int64", + "nullable": true, + "default": 0 + } + }, + { + "name": "id", + "in": "path", + "description": "ID of the share", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Remote share returned", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "token", + "remoteId" + ], + "properties": { + "token": { + "type": "string" + }, + "remoteId": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, + "400": { + "description": "Re-sharing is not possible", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + } + } + } + }, + "/ocs/v2.php/cloud/shares/{id}/permissions": { + "post": { + "operationId": "request_handler-update-permissions", + "summary": "update share information to keep federated re-shares in sync", + "tags": [ + "request_handler" + ], + "security": [ + {}, + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "token", + "in": "query", + "description": "Shared secret between servers", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "permissions", + "in": "query", + "description": "New permissions", + "schema": { + "type": "integer", + "format": "int64", + "nullable": true + } + }, + { + "name": "id", + "in": "path", + "description": "ID of the share", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Permissions updated successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "400": { + "description": "Updating permissions is not possible", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + } + } + } + }, + "/ocs/v2.php/cloud/shares/{id}/accept": { + "post": { + "operationId": "request_handler-accept-share", + "summary": "accept server-to-server share", + "tags": [ + "request_handler" + ], + "security": [ + {}, + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "token", + "in": "query", + "description": "Shared secret between servers", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "id", + "in": "path", + "description": "ID of the remote share", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Share accepted successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "500": { + "description": "", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + } + } + } + }, + "/ocs/v2.php/cloud/shares/{id}/decline": { + "post": { + "operationId": "request_handler-decline-share", + "summary": "decline server-to-server share", + "tags": [ + "request_handler" + ], + "security": [ + {}, + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "token", + "in": "query", + "description": "Shared secret between servers", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "id", + "in": "path", + "description": "ID of the remote share", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/cloud/shares/{id}/unshare": { + "post": { + "operationId": "request_handler-unshare", + "summary": "remove server-to-server share if it was unshared by the owner", + "tags": [ + "request_handler" + ], + "security": [ + {}, + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "token", + "in": "query", + "description": "Shared secret between servers", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "id", + "in": "path", + "description": "ID of the share", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/cloud/shares/{id}/revoke": { + "post": { + "operationId": "request_handler-revoke", + "summary": "federated share was revoked, either by the owner or the re-sharer", + "tags": [ + "request_handler" + ], + "security": [ + {}, + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "token", + "in": "query", + "description": "Shared secret between servers", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "id", + "in": "path", + "description": "ID of the share", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Share revoked successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "400": { + "description": "Revoking the share is not possible", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + } + } + } + }, + "/ocs/v2.php/cloud/shares/{id}/move": { + "post": { + "operationId": "request_handler-move", + "summary": "change the owner of a server-to-server share", + "tags": [ + "request_handler" + ], + "security": [ + {}, + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "token", + "in": "query", + "description": "Shared secret between servers", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "remote", + "in": "query", + "description": "Address of the remote", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "remote_id", + "in": "query", + "description": "ID of the remote", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "id", + "in": "path", + "description": "ID of the share", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Share moved successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "remote", + "owner" + ], + "properties": { + "remote": { + "type": "string" + }, + "owner": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, + "400": { + "description": "Moving share is not possible", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + } + } + } + } + }, + "tags": [ + { + "name": "mount_public_link", + "description": "Class MountPublicLinkController\nconvert public links to federated shares" + } + ] +} \ No newline at end of file diff --git a/lib/public/Federation/ICloudFederationProvider.php b/lib/public/Federation/ICloudFederationProvider.php index 7cb620848ef..121cb56bc4e 100644 --- a/lib/public/Federation/ICloudFederationProvider.php +++ b/lib/public/Federation/ICloudFederationProvider.php @@ -66,7 +66,7 @@ interface ICloudFederationProvider { * @param string $notificationType (e.g SHARE_ACCEPTED) * @param string $providerId share ID * @param array $notification provider specific notification - * @return array $data send back to sender + * @return array $data send back to sender * * @throws ShareNotFound * @throws ActionNotSupportedException