Skip to content

Commit c4b6096

Browse files
provokateurinprovokateurin
committed
core: Add OpenAPI spec
Signed-off-by: jld3103 <jld3103yt@gmail.com>
1 parent 706c141 commit c4b6096

39 files changed

Lines changed: 686 additions & 283 deletions

‎core/Controller/AppPasswordController.php‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
* @author Christoph Wurst <christoph@winzerhof-wurst.at>
99
* @author Daniel Kesselberg <mail@danielkesselberg.de>
1010
* @author Roeland Jago Douma <roeland@famdouma.nl>
11+
* @author Kate Döen <kate.doeen@nextcloud.com>
1112
*
1213
* @license GNU AGPL version 3 or any later version
1314
*
@@ -31,6 +32,7 @@
3132
use OC\Authentication\Exceptions\InvalidTokenException;
3233
use OC\Authentication\Token\IProvider;
3334
use OC\Authentication\Token\IToken;
35+
use OCP\AppFramework\Http;
3436
use OCP\AppFramework\Http\DataResponse;
3537
use OCP\AppFramework\OCS\OCSForbiddenException;
3638
use OCP\Authentication\Exceptions\CredentialsUnavailableException;
@@ -57,7 +59,12 @@ public function __construct(
5759
/**
5860
* @NoAdminRequired
5961
*
60-
* @throws OCSForbiddenException
62+
* Create app password
63+
*
64+
* @return DataResponse<Http::STATUS_OK, array{apppassword: string}, array{}>
65+
* @throws OCSForbiddenException Creating app password is not allowed
66+
*
67+
* 200: App password returned
6168
*/
6269
public function getAppPassword(): DataResponse {
6370
// We do not allow the creation of new tokens if this is an app password
@@ -102,6 +109,13 @@ public function getAppPassword(): DataResponse {
102109

103110
/**
104111
* @NoAdminRequired
112+
*
113+
* Delete app password
114+
*
115+
* @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
116+
* @throws OCSForbiddenException Deleting app password is not allowed
117+
*
118+
* 200: App password deleted successfully
105119
*/
106120
public function deleteAppPassword(): DataResponse {
107121
if (!$this->session->exists('app_password')) {
@@ -122,6 +136,13 @@ public function deleteAppPassword(): DataResponse {
122136

123137
/**
124138
* @NoAdminRequired
139+
*
140+
* Rotate app password
141+
*
142+
* @return DataResponse<Http::STATUS_OK, array{apppassword: string}, array{}>
143+
* @throws OCSForbiddenException Rotating app password is not allowed
144+
*
145+
* 200: App password returned
125146
*/
126147
public function rotateAppPassword(): DataResponse {
127148
if (!$this->session->exists('app_password')) {

‎core/Controller/AutoCompleteController.php‎

Lines changed: 39 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@
3030
*/
3131
namespace OC\Core\Controller;
3232

33+
use OCA\Core\ResponseDefinitions;
34+
use OCP\AppFramework\Http;
3335
use OCP\AppFramework\Http\DataResponse;
3436
use OCP\AppFramework\OCSController;
3537
use OCP\Collaboration\AutoComplete\AutoCompleteEvent;
@@ -39,6 +41,9 @@
3941
use OCP\IRequest;
4042
use OCP\Share\IShare;
4143

44+
/**
45+
* @psalm-import-type CoreAutocompleteResult from ResponseDefinitions
46+
*/
4247
class AutoCompleteController extends OCSController {
4348
public function __construct(
4449
string $appName,
@@ -52,7 +57,17 @@ public function __construct(
5257

5358
/**
5459
* @NoAdminRequired
60+
*
61+
* Autocomplete a query
62+
*
63+
* @param string $search Text to search for
64+
* @param string|null $itemType Type of the items to search for
65+
* @param string|null $itemId ID of the items to search for
5566
* @param string|null $sorter can be piped, top prio first, e.g.: "commenters|share-recipients"
67+
* @param int[] $shareTypes Types of shares to search for
68+
* @param int $limit Maximum number of results to return
69+
*
70+
* @return DataResponse<Http::STATUS_OK, CoreAutocompleteResult[], array{}>
5671
*/
5772
public function get(string $search, ?string $itemType, ?string $itemId, ?string $sorter = null, array $shareTypes = [IShare::TYPE_USER], int $limit = 10): DataResponse {
5873
// if enumeration/user listings are disabled, we'll receive an empty
@@ -89,18 +104,37 @@ public function get(string $search, ?string $itemType, ?string $itemId, ?string
89104
return new DataResponse($results);
90105
}
91106

107+
/**
108+
* @return CoreAutocompleteResult[]
109+
*/
92110
protected function prepareResultArray(array $results): array {
93111
$output = [];
112+
/** @var string $type */
94113
foreach ($results as $type => $subResult) {
95114
foreach ($subResult as $result) {
115+
/** @var ?string $icon */
116+
$icon = array_key_exists('icon', $result) ? $result['icon'] : null;
117+
118+
/** @var string $label */
119+
$label = $result['label'];
120+
121+
/** @var ?string $subline */
122+
$subline = array_key_exists('subline', $result) ? $result['subline'] : null;
123+
124+
/** @var ?string $status */
125+
$status = array_key_exists('status', $result) && is_string($result['status']) ? $result['status'] : null;
126+
127+
/** @var ?string $shareWithDisplayNameUnique */
128+
$shareWithDisplayNameUnique = array_key_exists('shareWithDisplayNameUnique', $result) ? $result['shareWithDisplayNameUnique'] : null;
129+
96130
$output[] = [
97131
'id' => (string) $result['value']['shareWith'],
98-
'label' => $result['label'],
99-
'icon' => $result['icon'] ?? '',
132+
'label' => $label,
133+
'icon' => $icon ?? '',
100134
'source' => $type,
101-
'status' => $result['status'] ?? '',
102-
'subline' => $result['subline'] ?? '',
103-
'shareWithDisplayNameUnique' => $result['shareWithDisplayNameUnique'] ?? '',
135+
'status' => $status ?? '',
136+
'subline' => $subline ?? '',
137+
'shareWithDisplayNameUnique' => $shareWithDisplayNameUnique ?? '',
104138
];
105139
}
106140
}

‎core/Controller/AvatarController.php‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
* @author Roeland Jago Douma <roeland@famdouma.nl>
1313
* @author Thomas Müller <thomas.mueller@tmit.eu>
1414
* @author Vincent Petry <vincent@nextcloud.com>
15+
* @author Kate Döen <kate.doeen@nextcloud.com>
1516
*
1617
* @license AGPL-3.0
1718
*
@@ -72,7 +73,14 @@ public function __construct(
7273
* @NoSameSiteCookieRequired
7374
* @PublicPage
7475
*
75-
* @return JSONResponse|FileDisplayResponse
76+
* Get the dark avatar
77+
*
78+
* @param string $userId ID of the user
79+
* @param int $size Size of the avatar
80+
* @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string, X-NC-IsCustomAvatar: int}>|JSONResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
81+
*
82+
* 200: Avatar returned
83+
* 404: Avatar not found
7684
*/
7785
public function getAvatarDark(string $userId, int $size) {
7886
if ($size <= 64) {
@@ -111,7 +119,14 @@ public function getAvatarDark(string $userId, int $size) {
111119
* @NoSameSiteCookieRequired
112120
* @PublicPage
113121
*
114-
* @return JSONResponse|FileDisplayResponse
122+
* Get the avatar
123+
*
124+
* @param string $userId ID of the user
125+
* @param int $size Size of the avatar
126+
* @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string, X-NC-IsCustomAvatar: int}>|JSONResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
127+
*
128+
* 200: Avatar returned
129+
* 404: Avatar not found
115130
*/
116131
public function getAvatar(string $userId, int $size) {
117132
if ($size <= 64) {

‎core/Controller/CSRFTokenController.php‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
*
88
* @author Christoph Wurst <christoph@winzerhof-wurst.at>
99
* @author Roeland Jago Douma <roeland@famdouma.nl>
10+
* @author Kate Döen <kate.doeen@nextcloud.com>
1011
*
1112
* @license GNU AGPL version 3 or any later version
1213
*
@@ -29,9 +30,11 @@
2930
use OC\Security\CSRF\CsrfTokenManager;
3031
use OCP\AppFramework\Controller;
3132
use OCP\AppFramework\Http;
33+
use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
3234
use OCP\AppFramework\Http\JSONResponse;
3335
use OCP\IRequest;
3436

37+
#[IgnoreOpenAPI]
3538
class CSRFTokenController extends Controller {
3639
public function __construct(
3740
string $appName,

‎core/Controller/ClientFlowLoginController.php‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
* @author Roeland Jago Douma <roeland@famdouma.nl>
1313
* @author RussellAult <RussellAult@users.noreply.github.com>
1414
* @author Sergej Nikolaev <kinolaev@gmail.com>
15+
* @author Kate Döen <kate.doeen@nextcloud.com>
1516
*
1617
* @license GNU AGPL version 3 or any later version
1718
*
@@ -41,6 +42,7 @@
4142
use OCA\OAuth2\Db\ClientMapper;
4243
use OCP\AppFramework\Controller;
4344
use OCP\AppFramework\Http;
45+
use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
4446
use OCP\AppFramework\Http\Attribute\UseSession;
4547
use OCP\AppFramework\Http\Response;
4648
use OCP\AppFramework\Http\StandaloneTemplateResponse;
@@ -56,6 +58,7 @@
5658
use OCP\Security\ISecureRandom;
5759
use OCP\Session\Exceptions\SessionNotAvailableException;
5860

61+
#[IgnoreOpenAPI]
5962
class ClientFlowLoginController extends Controller {
6063
public const STATE_NAME = 'client.flow.state.token';
6164

‎core/Controller/ClientFlowLoginV2Controller.php‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,10 @@
3131
use OC\Core\Db\LoginFlowV2;
3232
use OC\Core\Exception\LoginFlowV2NotFoundException;
3333
use OC\Core\Service\LoginFlowV2Service;
34+
use OCA\Core\ResponseDefinitions;
3435
use OCP\AppFramework\Controller;
3536
use OCP\AppFramework\Http;
37+
use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
3638
use OCP\AppFramework\Http\Attribute\UseSession;
3739
use OCP\AppFramework\Http\JSONResponse;
3840
use OCP\AppFramework\Http\RedirectResponse;
@@ -47,6 +49,10 @@
4749
use OCP\IUserSession;
4850
use OCP\Security\ISecureRandom;
4951

52+
/**
53+
* @psalm-import-type CoreLoginFlowV2Credentials from ResponseDefinitions
54+
* @psalm-import-type CoreLoginFlowV2 from ResponseDefinitions
55+
*/
5056
class ClientFlowLoginV2Controller extends Controller {
5157
public const TOKEN_NAME = 'client.flow.v2.login.token';
5258
public const STATE_NAME = 'client.flow.v2.state.token';
@@ -69,6 +75,14 @@ public function __construct(
6975
/**
7076
* @NoCSRFRequired
7177
* @PublicPage
78+
*
79+
* Poll the login flow credentials
80+
*
81+
* @param string $token Token of the flow
82+
* @return JSONResponse<Http::STATUS_OK, CoreLoginFlowV2Credentials, array{}>|JSONResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
83+
*
84+
* 200: Login flow credentials returned
85+
* 404: Login flow not found or completed
7286
*/
7387
public function poll(string $token): JSONResponse {
7488
try {
@@ -77,13 +91,14 @@ public function poll(string $token): JSONResponse {
7791
return new JSONResponse([], Http::STATUS_NOT_FOUND);
7892
}
7993

80-
return new JSONResponse($creds);
94+
return new JSONResponse($creds->jsonSerialize());
8195
}
8296

8397
/**
8498
* @NoCSRFRequired
8599
* @PublicPage
86100
*/
101+
#[IgnoreOpenAPI]
87102
#[UseSession]
88103
public function landing(string $token, $user = ''): Response {
89104
if (!$this->loginFlowV2Service->startLoginFlow($token)) {
@@ -101,6 +116,7 @@ public function landing(string $token, $user = ''): Response {
101116
* @NoCSRFRequired
102117
* @PublicPage
103118
*/
119+
#[IgnoreOpenAPI]
104120
#[UseSession]
105121
public function showAuthPickerPage($user = ''): StandaloneTemplateResponse {
106122
try {
@@ -134,6 +150,7 @@ public function showAuthPickerPage($user = ''): StandaloneTemplateResponse {
134150
* @NoCSRFRequired
135151
* @NoSameSiteCookieRequired
136152
*/
153+
#[IgnoreOpenAPI]
137154
#[UseSession]
138155
public function grantPage(?string $stateToken): StandaloneTemplateResponse {
139156
if ($stateToken === null) {
@@ -267,6 +284,10 @@ private function handleFlowDone(bool $result): StandaloneTemplateResponse {
267284
/**
268285
* @NoCSRFRequired
269286
* @PublicPage
287+
*
288+
* Init a login flow
289+
*
290+
* @return JSONResponse<Http::STATUS_OK, CoreLoginFlowV2, array{}>
270291
*/
271292
public function init(): JSONResponse {
272293
// Get client user agent

0 commit comments

Comments
 (0)