Skip to content

Commit 706c141

Browse files
provokateurinprovokateurin
authored
Merge pull request #39327 from nextcloud/feature/openapi/files
files: Add OpenAPI spec
2 parents 329d142 + 259264b commit 706c141

14 files changed

+2120
-10
lines changed

‎apps/files/composer/composer/autoload_classmap.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@
6161
'OCA\\Files\\Migration\\Version11301Date20191205150729' => $baseDir . '/../lib/Migration/Version11301Date20191205150729.php',
6262
'OCA\\Files\\Migration\\Version12101Date20221011153334' => $baseDir . '/../lib/Migration/Version12101Date20221011153334.php',
6363
'OCA\\Files\\Notification\\Notifier' => $baseDir . '/../lib/Notification/Notifier.php',
64+
'OCA\\Files\\ResponseDefinitions' => $baseDir . '/../lib/ResponseDefinitions.php',
6465
'OCA\\Files\\Search\\FilesSearchProvider' => $baseDir . '/../lib/Search/FilesSearchProvider.php',
6566
'OCA\\Files\\Service\\DirectEditingService' => $baseDir . '/../lib/Service/DirectEditingService.php',
6667
'OCA\\Files\\Service\\OwnershipTransferService' => $baseDir . '/../lib/Service/OwnershipTransferService.php',

‎apps/files/composer/composer/autoload_static.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ class ComposerStaticInitFiles
7676
'OCA\\Files\\Migration\\Version11301Date20191205150729' => __DIR__ . '/..' . '/../lib/Migration/Version11301Date20191205150729.php',
7777
'OCA\\Files\\Migration\\Version12101Date20221011153334' => __DIR__ . '/..' . '/../lib/Migration/Version12101Date20221011153334.php',
7878
'OCA\\Files\\Notification\\Notifier' => __DIR__ . '/..' . '/../lib/Notification/Notifier.php',
79+
'OCA\\Files\\ResponseDefinitions' => __DIR__ . '/..' . '/../lib/ResponseDefinitions.php',
7980
'OCA\\Files\\Search\\FilesSearchProvider' => __DIR__ . '/..' . '/../lib/Search/FilesSearchProvider.php',
8081
'OCA\\Files\\Service\\DirectEditingService' => __DIR__ . '/..' . '/../lib/Service/DirectEditingService.php',
8182
'OCA\\Files\\Service\\OwnershipTransferService' => __DIR__ . '/..' . '/../lib/Service/OwnershipTransferService.php',

‎apps/files/lib/Capabilities.php‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,12 +38,14 @@ public function __construct(IConfig $config) {
3838

3939
/**
4040
* Return this classes capabilities
41+
*
42+
* @return array{files: array{bigfilechunking: bool, blacklisted_files: array<mixed>}}
4143
*/
4244
public function getCapabilities() {
4345
return [
4446
'files' => [
4547
'bigfilechunking' => true,
46-
'blacklisted_files' => $this->config->getSystemValue('blacklisted_files', ['.htaccess'])
48+
'blacklisted_files' => (array)$this->config->getSystemValue('blacklisted_files', ['.htaccess'])
4749
],
4850
];
4951
}

‎apps/files/lib/Controller/ApiController.php‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,6 @@
6060
use OCP\Share\IShare;
6161

6262
/**
63-
* Class ApiController
64-
*
6563
* @package OCA\Files\Controller
6664
*/
6765
class ApiController extends Controller {
@@ -104,10 +102,14 @@ public function __construct(string $appName,
104102
* @NoCSRFRequired
105103
* @StrictCookieRequired
106104
*
107-
* @param int $x
108-
* @param int $y
105+
* @param int $x Width of the thumbnail
106+
* @param int $y Height of the thumbnail
109107
* @param string $file URL-encoded filename
110-
* @return DataResponse|FileDisplayResponse
108+
* @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND, array{message?: string}, array{}>
109+
*
110+
* 200: Thumbnail returned
111+
* 400: Getting thumbnail is not possible
112+
* 404: File not found
111113
*/
112114
public function getThumbnail($x, $y, $file) {
113115
if ($x < 1 || $y < 1) {
@@ -386,6 +388,12 @@ public function getGridView() {
386388
/**
387389
* @NoAdminRequired
388390
* @NoCSRFRequired
391+
*
392+
* Get the service-worker Javascript for previews
393+
*
394+
* @psalm-suppress MoreSpecificReturnType The value of Service-Worker-Allowed is not relevant
395+
* @psalm-suppress LessSpecificReturnStatement The value of Service-Worker-Allowed is not relevant
396+
* @return StreamResponse<Http::STATUS_OK, array{Content-Type: 'application/javascript', Service-Worker-Allowed: string}>
389397
*/
390398
public function serviceWorker(): StreamResponse {
391399
$response = new StreamResponse(__DIR__ . '/../../../../dist/preview-service-worker.js');

‎apps/files/lib/Controller/DirectEditingController.php‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,9 @@ public function __construct($appName, IRequest $request, $corsMethods, $corsAllo
6363

6464
/**
6565
* @NoAdminRequired
66+
*
67+
* Get the direct editing capabilities
68+
* @return DataResponse<Http::STATUS_OK, array{editors: array<string, array{id: string, name: string, mimetypes: string[], optionalMimetypes: string[], secure: bool}>, creators: array<string, array{id: string, editor: string, name: string, extension: string, templates: bool, mimetypes: string[]}>}, array{}>
6669
*/
6770
public function info(): DataResponse {
6871
$response = new DataResponse($this->directEditingService->getDirectEditingCapabilitites());
@@ -72,6 +75,18 @@ public function info(): DataResponse {
7275

7376
/**
7477
* @NoAdminRequired
78+
*
79+
* Create a file for direct editing
80+
*
81+
* @param string $path Path of the file
82+
* @param string $editorId ID of the editor
83+
* @param string $creatorId ID of the creator
84+
* @param ?string $templateId ID of the template
85+
*
86+
* @return DataResponse<Http::STATUS_OK, array{url: string}, array{}>|DataResponse<Http::STATUS_FORBIDDEN|Http::STATUS_INTERNAL_SERVER_ERROR, array{message: string}, array{}>
87+
*
88+
* 200: URL for direct editing returned
89+
* 403: Opening file is not allowed
7590
*/
7691
public function create(string $path, string $editorId, string $creatorId, string $templateId = null): DataResponse {
7792
if (!$this->directEditingManager->isEnabled()) {
@@ -92,6 +107,17 @@ public function create(string $path, string $editorId, string $creatorId, string
92107

93108
/**
94109
* @NoAdminRequired
110+
*
111+
* Open a file for direct editing
112+
*
113+
* @param string $path Path of the file
114+
* @param ?string $editorId ID of the editor
115+
* @param ?int $fileId ID of the file
116+
*
117+
* @return DataResponse<Http::STATUS_OK, array{url: string}, array{}>|DataResponse<Http::STATUS_FORBIDDEN|Http::STATUS_INTERNAL_SERVER_ERROR, array{message: string}, array{}>
118+
*
119+
* 200: URL for direct editing returned
120+
* 403: Opening file is not allowed
95121
*/
96122
public function open(string $path, string $editorId = null, ?int $fileId = null): DataResponse {
97123
if (!$this->directEditingManager->isEnabled()) {
@@ -114,6 +140,15 @@ public function open(string $path, string $editorId = null, ?int $fileId = null)
114140

115141
/**
116142
* @NoAdminRequired
143+
*
144+
* Get the templates for direct editing
145+
*
146+
* @param string $editorId ID of the editor
147+
* @param string $creatorId ID of the creator
148+
*
149+
* @return DataResponse<Http::STATUS_OK, array{templates: array<string, array{id: string, title: string, preview: ?string, extension: string, mimetype: string}>}, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR, array{message: string}, array{}>
150+
*
151+
* 200: Templates returned
117152
*/
118153
public function templates(string $editorId, string $creatorId): DataResponse {
119154
if (!$this->directEditingManager->isEnabled()) {

‎apps/files/lib/Controller/DirectEditingViewController.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424

2525
use Exception;
2626
use OCP\AppFramework\Controller;
27+
use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
2728
use OCP\AppFramework\Http\NotFoundResponse;
2829
use OCP\AppFramework\Http\Response;
2930
use OCP\DirectEditing\IManager;
@@ -32,6 +33,7 @@
3233
use OCP\ILogger;
3334
use OCP\IRequest;
3435

36+
#[IgnoreOpenAPI]
3537
class DirectEditingViewController extends Controller {
3638

3739
/** @var IEventDispatcher */

‎apps/files/lib/Controller/OpenLocalEditorController.php‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,14 @@ public function __construct(
7070
/**
7171
* @NoAdminRequired
7272
* @UserRateThrottle(limit=10, period=120)
73+
*
74+
* Create a local editor
75+
*
76+
* @param string $path Path of the file
77+
*
78+
* @return DataResponse<Http::STATUS_OK, array{userId: ?string, pathHash: string, expirationTime: int, token: string}, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR, array<empty>, array{}>
79+
*
80+
* 200: Local editor returned
7381
*/
7482
public function create(string $path): DataResponse {
7583
$pathHash = sha1($path);
@@ -107,6 +115,16 @@ public function create(string $path): DataResponse {
107115
/**
108116
* @NoAdminRequired
109117
* @BruteForceProtection(action=openLocalEditor)
118+
*
119+
* Validate a local editor
120+
*
121+
* @param string $path Path of the file
122+
* @param string $token Token of the local editor
123+
*
124+
* @return DataResponse<Http::STATUS_OK, array{userId: string, pathHash: string, expirationTime: int, token: string}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
125+
*
126+
* 200: Local editor validated successfully
127+
* 404: Local editor not found
110128
*/
111129
public function validate(string $path, string $token): DataResponse {
112130
$pathHash = sha1($path);

‎apps/files/lib/Controller/TemplateController.php‎

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,13 +26,21 @@
2626
*/
2727
namespace OCA\Files\Controller;
2828

29+
use OCA\Files\ResponseDefinitions;
30+
use OCP\AppFramework\Http;
2931
use OCP\AppFramework\Http\DataResponse;
3032
use OCP\AppFramework\OCS\OCSForbiddenException;
3133
use OCP\AppFramework\OCSController;
3234
use OCP\Files\GenericFileException;
3335
use OCP\Files\Template\ITemplateManager;
36+
use OCP\Files\Template\TemplateFileCreator;
3437
use OCP\IRequest;
3538

39+
/**
40+
* @psalm-import-type FilesTemplate from ResponseDefinitions
41+
* @psalm-import-type FilesTemplateFile from ResponseDefinitions
42+
* @psalm-import-type FilesTemplateFileCreator from ResponseDefinitions
43+
*/
3644
class TemplateController extends OCSController {
3745
protected $templateManager;
3846

@@ -43,14 +51,28 @@ public function __construct($appName, IRequest $request, ITemplateManager $templ
4351

4452
/**
4553
* @NoAdminRequired
54+
*
55+
* List the available templates
56+
*
57+
* @return DataResponse<Http::STATUS_OK, array<FilesTemplateFileCreator>, array{}>
4658
*/
4759
public function list(): DataResponse {
4860
return new DataResponse($this->templateManager->listTemplates());
4961
}
5062

5163
/**
5264
* @NoAdminRequired
53-
* @throws OCSForbiddenException
65+
*
66+
* Create a template
67+
*
68+
* @param string $filePath Path of the file
69+
* @param string $templatePath Name of the template
70+
* @param string $templateType Type of the template
71+
*
72+
* @return DataResponse<Http::STATUS_OK, FilesTemplateFile, array{}>
73+
* @throws OCSForbiddenException Creating template is not allowed
74+
*
75+
* 200: Template created successfully
5476
*/
5577
public function create(string $filePath, string $templatePath = '', string $templateType = 'user'): DataResponse {
5678
try {
@@ -62,13 +84,24 @@ public function create(string $filePath, string $templatePath = '', string $temp
6284

6385
/**
6486
* @NoAdminRequired
87+
*
88+
* Initialize the template directory
89+
*
90+
* @param string $templatePath Path of the template directory
91+
* @param bool $copySystemTemplates Whether to copy the system templates to the template directory
92+
*
93+
* @return DataResponse<Http::STATUS_OK, array{template_path: string, templates: FilesTemplateFileCreator[]}, array{}>
94+
* @throws OCSForbiddenException Initializing the template directory is not allowed
95+
*
96+
* 200: Template directory initialized successfully
6597
*/
6698
public function path(string $templatePath = '', bool $copySystemTemplates = false) {
6799
try {
100+
/** @var string $templatePath */
68101
$templatePath = $this->templateManager->initializeTemplateDirectory($templatePath, null, $copySystemTemplates);
69102
return new DataResponse([
70103
'template_path' => $templatePath,
71-
'templates' => $this->templateManager->listCreators()
104+
'templates' => array_map(fn(TemplateFileCreator $creator) => $creator->jsonSerialize(), $this->templateManager->listCreators()),
72105
]);
73106
} catch (\Exception $e) {
74107
throw new OCSForbiddenException($e->getMessage());

‎apps/files/lib/Controller/TransferOwnershipController.php‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,17 @@ public function __construct(string $appName,
8282

8383
/**
8484
* @NoAdminRequired
85+
*
86+
* Transfer the ownership to another user
87+
*
88+
* @param string $recipient Username of the recipient
89+
* @param string $path Path of the file
90+
*
91+
* @return DataResponse<Http::STATUS_OK|Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN, array<empty>, array{}>
92+
*
93+
* 200: Ownership transferred successfully
94+
* 400: Transferring ownership is not possible
95+
* 403: Transferring ownership is not allowed
8596
*/
8697
public function transfer(string $recipient, string $path): DataResponse {
8798
$recipientUser = $this->userManager->get($recipient);
@@ -127,6 +138,16 @@ public function transfer(string $recipient, string $path): DataResponse {
127138

128139
/**
129140
* @NoAdminRequired
141+
*
142+
* Accept an ownership transfer
143+
*
144+
* @param int $id ID of the ownership transfer
145+
*
146+
* @return DataResponse<Http::STATUS_OK|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>
147+
*
148+
* 200: Ownership transfer accepted successfully
149+
* 403: Accepting ownership transfer is not allowed
150+
* 404: Ownership transfer not found
130151
*/
131152
public function accept(int $id): DataResponse {
132153
try {
@@ -160,6 +181,16 @@ public function accept(int $id): DataResponse {
160181

161182
/**
162183
* @NoAdminRequired
184+
*
185+
* Reject an ownership transfer
186+
*
187+
* @param int $id ID of the ownership transfer
188+
*
189+
* @return DataResponse<Http::STATUS_OK|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>
190+
*
191+
* 200: Ownership transfer rejected successfully
192+
* 403: Rejecting ownership transfer is not allowed
193+
* 404: Ownership transfer not found
163194
*/
164195
public function reject(int $id): DataResponse {
165196
try {

‎apps/files/lib/Controller/ViewController.php‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@
3535
*/
3636
namespace OCA\Files\Controller;
3737

38+
use OC\AppFramework\Http;
3839
use OCA\Files\Activity\Helper;
3940
use OCA\Files\AppInfo\Application;
4041
use OCA\Files\Event\LoadAdditionalScriptsEvent;
@@ -44,6 +45,7 @@
4445
use OCA\Viewer\Event\LoadViewer;
4546
use OCP\App\IAppManager;
4647
use OCP\AppFramework\Controller;
48+
use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
4749
use OCP\AppFramework\Http\ContentSecurityPolicy;
4850
use OCP\AppFramework\Http\RedirectResponse;
4951
use OCP\AppFramework\Http\Response;
@@ -63,10 +65,9 @@
6365
use OCP\Share\IManager;
6466

6567
/**
66-
* Class ViewController
67-
*
6868
* @package OCA\Files\Controller
6969
*/
70+
#[IgnoreOpenAPI]
7071
class ViewController extends Controller {
7172
private IURLGenerator $urlGenerator;
7273
private IL10N $l10n;

0 commit comments

Comments
 (0)