Merge pull request #40502 from nextcloud/fix/openapi/single-status-de…

…scriptions Add single status code descriptions for OpenAPI
nextcloud · Sep 27, 2023 · f134244 · f134244
2 parents 6fb5f97 + c2d45cb
commit f134244
Show file tree

Hide file tree

Showing 44 changed files with 228 additions and 130 deletions.
diff --git a/apps/dashboard/lib/Controller/DashboardApiController.php b/apps/dashboard/lib/Controller/DashboardApiController.php
@@ -104,6 +104,8 @@ static function (IWidget $widget) use ($widgetIds) {
 	 * @param int $limit Limit number of result items per widget
 	 * @param string[] $widgets Limit results to specific widgets
 	 * @return DataResponse<Http::STATUS_OK, array<string, DashboardWidgetItem[]>, array{}>
+	 *
+	 * 200: Widget items returned
 	 */
 	public function getWidgetItems(array $sinceIds = [], int $limit = 7, array $widgets = []): DataResponse {
 		$items = [];
@@ -129,6 +131,8 @@ public function getWidgetItems(array $sinceIds = [], int $limit = 7, array $widg
 	 * @param int $limit Limit number of result items per widget
 	 * @param string[] $widgets Limit results to specific widgets
 	 * @return DataResponse<Http::STATUS_OK, array<string, DashboardWidgetItems>, array{}>
+	 *
+	 * 200: Widget items returned
 	 */
 	public function getWidgetItemsV2(array $sinceIds = [], int $limit = 7, array $widgets = []): DataResponse {
 		$items = [];
@@ -151,6 +155,8 @@ public function getWidgetItemsV2(array $sinceIds = [], int $limit = 7, array $wi
 	 * @NoCSRFRequired
 	 *
 	 * @return DataResponse<Http::STATUS_OK, array<string, DashboardWidget>, array{}>
+	 *
+	 * 200: Widgets returned
 	 */
 	public function getWidgets(): DataResponse {
 		$widgets = $this->dashboardManager->getWidgets();

diff --git a/apps/dashboard/openapi.json b/apps/dashboard/openapi.json
@@ -200,7 +200,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "",
+                        "description": "Widgets returned",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -293,7 +293,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "",
+                        "description": "Widget items returned",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -389,7 +389,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "",
+                        "description": "Widget items returned",
                         "content": {
                             "application/json": {
                                 "schema": {

diff --git a/apps/federatedfilesharing/lib/Controller/RequestHandlerController.php b/apps/federatedfilesharing/lib/Controller/RequestHandlerController.php
@@ -134,6 +134,8 @@ public function __construct(string $appName,
 	 * @param string|null $ownerFederatedId Federated ID of the receiver
 	 * @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
 	 * @throws OCSException
+	 *
+	 * 200: Share created successfully
 	 */
 	public function createShare(
 		?string $remote = null,
@@ -284,6 +286,8 @@ public function acceptShare(int $id, ?string $token = null) {
 	 * @param string|null $token Shared secret between servers
 	 * @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
 	 * @throws OCSException
+	 *
+	 * 200: Share declined successfully
 	 */
 	public function declineShare(int $id, ?string $token = null) {
 		$notification = [
@@ -316,6 +320,8 @@ public function declineShare(int $id, ?string $token = null) {
 	 * @param string|null $token Shared secret between servers
 	 * @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
 	 * @throws OCSException
+	 *
+	 * 200: Share unshared successfully
 	 */
 	public function unshare(int $id, ?string $token = null) {
 		if (!$this->isS2SEnabled()) {

diff --git a/apps/federatedfilesharing/openapi.json b/apps/federatedfilesharing/openapi.json
@@ -243,7 +243,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "",
+                        "description": "Share created successfully",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -629,7 +629,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "",
+                        "description": "Share declined successfully",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -707,7 +707,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "",
+                        "description": "Share unshared successfully",
                         "content": {
                             "application/json": {
                                 "schema": {

diff --git a/apps/files/lib/Controller/ApiController.php b/apps/files/lib/Controller/ApiController.php
@@ -43,6 +43,7 @@
 use OCA\Files\Service\ViewConfig;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\ContentSecurityPolicy;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\Http\FileDisplayResponse;
@@ -389,13 +390,8 @@ public function getGridView() {
 	 * @NoAdminRequired
 	 * @NoCSRFRequired
 	 * @PublicPage
-	 *
-	 * Get the service-worker Javascript for previews
-	 *
-	 * @psalm-suppress MoreSpecificReturnType The value of Service-Worker-Allowed is not relevant
-	 * @psalm-suppress LessSpecificReturnStatement The value of Service-Worker-Allowed is not relevant
-	 * @return StreamResponse<Http::STATUS_OK, array{Content-Type: 'application/javascript', Service-Worker-Allowed: string}>
 	 */
+	#[IgnoreOpenAPI]
 	public function serviceWorker(): StreamResponse {
 		$response = new StreamResponse(__DIR__ . '/../../../../dist/preview-service-worker.js');
 		$response->setHeaders([

diff --git a/apps/files/lib/Controller/DirectEditingController.php b/apps/files/lib/Controller/DirectEditingController.php
@@ -55,6 +55,8 @@ public function __construct(
 	 *
 	 * Get the direct editing capabilities
 	 * @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{}>
+	 *
+	 * 200: Direct editing capabilities returned
 	 */
 	public function info(): DataResponse {
 		$response = new DataResponse($this->directEditingService->getDirectEditingCapabilitites());

diff --git a/apps/files/lib/Controller/TemplateController.php b/apps/files/lib/Controller/TemplateController.php
@@ -55,6 +55,8 @@ public function __construct($appName, IRequest $request, ITemplateManager $templ
 	 * List the available templates
 	 *
 	 * @return DataResponse<Http::STATUS_OK, array<FilesTemplateFileCreator>, array{}>
+	 *
+	 * 200: Available templates returned
 	 */
 	public function list(): DataResponse {
 		return new DataResponse($this->templateManager->listTemplates());

diff --git a/apps/files/openapi.json b/apps/files/openapi.json
@@ -332,44 +332,6 @@
                 }
             }
         },
-        "/index.php/apps/files/preview-service-worker.js": {
-            "get": {
-                "operationId": "api-service-worker",
-                "summary": "Get the service-worker Javascript for previews",
-                "tags": [
-                    "api"
-                ],
-                "security": [
-                    {},
-                    {
-                        "bearer_auth": []
-                    },
-                    {
-                        "basic_auth": []
-                    }
-                ],
-                "responses": {
-                    "200": {
-                        "description": "",
-                        "headers": {
-                            "Service-Worker-Allowed": {
-                                "schema": {
-                                    "type": "string"
-                                }
-                            }
-                        },
-                        "content": {
-                            "application/javascript": {
-                                "schema": {
-                                    "type": "string",
-                                    "format": "binary"
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-        },
         "/ocs/v2.php/apps/files/api/v1/directEditing": {
             "get": {
                 "operationId": "direct_editing-info",
@@ -398,7 +360,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "",
+                        "description": "Direct editing capabilities returned",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -1041,7 +1003,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "",
+                        "description": "Available templates returned",
                         "content": {
                             "application/json": {
                                 "schema": {

diff --git a/apps/files_external/lib/Controller/ApiController.php b/apps/files_external/lib/Controller/ApiController.php
@@ -101,6 +101,8 @@ private function formatMount(string $mountPoint, StorageConfig $mountConfig): ar
 	 * Get the mount points visible for this user
 	 *
 	 * @return DataResponse<Http::STATUS_OK, FilesExternalMount[], array{}>
+	 *
+	 * 200: User mounts returned
 	 */
 	public function getUserMounts(): DataResponse {
 		$entries = [];

diff --git a/apps/files_external/openapi.json b/apps/files_external/openapi.json
@@ -198,7 +198,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "",
+                        "description": "User mounts returned",
                         "content": {
                             "application/json": {
                                 "schema": {

diff --git a/apps/files_sharing/lib/Controller/DeletedShareAPIController.php b/apps/files_sharing/lib/Controller/DeletedShareAPIController.php
@@ -188,6 +188,8 @@ private function formatShare(IShare $share): array {
 	 * Get a list of all deleted shares
 	 *
 	 * @return DataResponse<Http::STATUS_OK, FilesSharingDeletedShare[], array{}>
+	 *
+	 * 200: Deleted shares returned
 	 */
 	public function index(): DataResponse {
 		$groupShares = $this->shareManager->getDeletedSharedWith($this->userId, IShare::TYPE_GROUP, null, -1, 0);

diff --git a/apps/files_sharing/lib/Controller/RemoteController.php b/apps/files_sharing/lib/Controller/RemoteController.php
@@ -62,6 +62,8 @@ public function __construct(
 	 * Get list of pending remote shares
 	 *
 	 * @return DataResponse<Http::STATUS_OK, FilesSharingRemoteShare[], array{}>
+	 *
+	 * 200: Pending remote shares returned
 	 */
 	public function getOpenShares() {
 		return new DataResponse($this->externalManager->getOpenShares());
@@ -138,6 +140,8 @@ private static function extendShareInfo($share) {
 	 * Get a list of accepted remote shares
 	 *
 	 * @return DataResponse<Http::STATUS_OK, FilesSharingRemoteShare[], array{}>
+	 *
+	 * 200: Accepted remote shares returned
 	 */
 	public function getShares() {
 		$shares = $this->externalManager->getAcceptedShares();

diff --git a/apps/files_sharing/lib/Controller/ShareAPIController.php b/apps/files_sharing/lib/Controller/ShareAPIController.php
@@ -1410,6 +1410,8 @@ public function updateShare(
 	 * Get all shares that are still pending
 	 *
 	 * @return DataResponse<Http::STATUS_OK, FilesSharingShare[], array{}>
+	 *
+	 * 200: Pending shares returned
 	 */
 	public function pendingShares(): DataResponse {
 		$pendingShares = [];

diff --git a/apps/files_sharing/lib/Controller/ShareesAPIController.php b/apps/files_sharing/lib/Controller/ShareesAPIController.php
@@ -348,6 +348,8 @@ private function getAllSharees(string $user, array $shareTypes): ISearchResult {
 	 * @param string $itemType Limit to specific item types
 	 * @param int|int[]|null $shareType Limit to specific share types
 	 * @return DataResponse<Http::STATUS_OK, FilesSharingShareesRecommendedResult, array{}>
+	 *
+	 * 200: Recommended sharees returned
 	 */
 	public function findRecommended(string $itemType, $shareType = null): DataResponse {
 		$shareTypes = [

diff --git a/apps/files_sharing/openapi.json b/apps/files_sharing/openapi.json
@@ -2107,7 +2107,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "",
+                        "description": "Pending shares returned",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -2609,7 +2609,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "",
+                        "description": "Deleted shares returned",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -2900,7 +2900,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "",
+                        "description": "Recommended sharees returned",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -2960,7 +2960,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "",
+                        "description": "Accepted remote shares returned",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -3023,7 +3023,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "",
+                        "description": "Pending remote shares returned",
                         "content": {
                             "application/json": {
                                 "schema": {

diff --git a/apps/provisioning_api/lib/Controller/AppConfigController.php b/apps/provisioning_api/lib/Controller/AppConfigController.php
@@ -88,6 +88,8 @@ public function __construct(string $appName,
 	 * Get a list of apps
 	 *
 	 * @return DataResponse<Http::STATUS_OK, array{data: string[]}, array{}>
+	 *
+	 * 200: Apps returned
 	 */
 	public function getApps(): DataResponse {
 		return new DataResponse([

diff --git a/apps/provisioning_api/lib/Controller/AppsController.php b/apps/provisioning_api/lib/Controller/AppsController.php
@@ -62,6 +62,8 @@ public function __construct(
 	 * @param ?string $filter Filter for enabled or disabled apps
 	 * @return DataResponse<Http::STATUS_OK, array{apps: string[]}, array{}>
 	 * @throws OCSException
+	 *
+	 * 200: Installed apps returned
 	 */
 	public function getApps(?string $filter = null): DataResponse {
 		$apps = (new OC_App())->listAllApps();
@@ -94,6 +96,8 @@ public function getApps(?string $filter = null): DataResponse {
 	 * @param string $app ID of the app
 	 * @return DataResponse<Http::STATUS_OK, ProvisioningApiAppInfo, array{}>
 	 * @throws OCSException
+	 *
+	 * 200: App info returned
 	 */
 	public function getAppInfo(string $app): DataResponse {
 		$info = $this->appManager->getAppInfo($app);
@@ -112,6 +116,8 @@ public function getAppInfo(string $app): DataResponse {
 	 * @param string $app ID of the app
 	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
 	 * @throws OCSException
+	 *
+	 * 200: App enabled successfully
 	 */
 	public function enable(string $app): DataResponse {
 		try {
@@ -129,6 +135,8 @@ public function enable(string $app): DataResponse {
 	 *
 	 * @param string $app ID of the app
 	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 *
+	 * 200: App disabled successfully
 	 */
 	public function disable(string $app): DataResponse {
 		$this->appManager->disableApp($app);