Merge pull request #39257 from nextcloud/feature/openapi/comments

comments: Add OpenAPI spec

3 files changed, 112 insertions, 4 deletions

diff --git a/apps/comments/lib/Capabilities.php b/apps/comments/lib/Capabilities.php
index ba5d2a2086b..597f248412c 100644
--- a/apps/comments/lib/Capabilities.php
+++ b/apps/comments/lib/Capabilities.php
@@ -28,6 +28,9 @@ namespace OCA\Comments;
 use OCP\Capabilities\ICapability;
 
 class Capabilities implements ICapability {
+	/**
+	 * @return array{files: array{comments: bool}}
+	 */
 	public function getCapabilities(): array {
 		return [
 			'files' => [
diff --git a/apps/comments/lib/Controller/NotificationsController.php b/apps/comments/lib/Controller/NotificationsController.php
index 41a9541a684..0186f8bc736 100644
--- a/apps/comments/lib/Controller/NotificationsController.php
+++ b/apps/comments/lib/Controller/NotificationsController.php
@@ -27,7 +27,7 @@ namespace OCA\Comments\Controller;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http\NotFoundResponse;
 use OCP\AppFramework\Http\RedirectResponse;
-use OCP\AppFramework\Http\Response;
+use OCP\AppFramework\Http;
 use OCP\Comments\IComment;
 use OCP\Comments\ICommentsManager;
 use OCP\Files\IRootFolder;
@@ -38,8 +38,6 @@ use OCP\IUserSession;
 use OCP\Notification\IManager;
 
 /**
- * Class NotificationsController
- *
  * @package OCA\Comments\Controller
  */
 class NotificationsController extends Controller {
@@ -73,8 +71,17 @@ class NotificationsController extends Controller {
 	/**
 	 * @PublicPage
 	 * @NoCSRFRequired
+	 *
+	 * View a notification
+	 *
+	 * @param string $id ID of the notification
+	 *
+	 * @return RedirectResponse<Http::STATUS_SEE_OTHER, array{}>|NotFoundResponse<Http::STATUS_NOT_FOUND, array{}>
+	 *
+	 * 303: Redirected to notification
+	 * 404: Notification not found
 	 */
-	public function view(string $id): Response {
+	public function view(string $id): RedirectResponse|NotFoundResponse {
 		$currentUser = $this->userSession->getUser();
 		if (!$currentUser instanceof IUser) {
 			return new RedirectResponse(
diff --git a/apps/comments/openapi.json b/apps/comments/openapi.json
new file mode 100644
index 00000000000..fcb370bbd4e
--- /dev/null
+++ b/apps/comments/openapi.json
@@ -0,0 +1,98 @@
+{
+    "openapi": "3.0.3",
+    "info": {
+        "title": "comments",
+        "version": "0.0.1",
+        "description": "Files app plugin to add comments to files",
+        "license": {
+            "name": "agpl"
+        }
+    },
+    "components": {
+        "securitySchemes": {
+            "basic_auth": {
+                "type": "http",
+                "scheme": "basic"
+            },
+            "bearer_auth": {
+                "type": "http",
+                "scheme": "bearer"
+            }
+        },
+        "schemas": {
+            "Capabilities": {
+                "type": "object",
+                "required": [
+                    "files"
+                ],
+                "properties": {
+                    "files": {
+                        "type": "object",
+                        "required": [
+                            "comments"
+                        ],
+                        "properties": {
+                            "comments": {
+                                "type": "boolean"
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "paths": {
+        "/index.php/apps/comments/notifications/view/{id}": {
+            "get": {
+                "operationId": "notifications-view",
+                "summary": "View a notification",
+                "tags": [
+                    "notifications"
+                ],
+                "security": [
+                    {},
+                    {
+                        "bearer_auth": []
+                    },
+                    {
+                        "basic_auth": []
+                    }
+                ],
+                "parameters": [
+                    {
+                        "name": "id",
+                        "in": "path",
+                        "description": "ID of the notification",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    }
+                ],
+                "responses": {
+                    "303": {
+                        "description": "Redirected to notification",
+                        "headers": {
+                            "Location": {
+                                "schema": {
+                                    "type": "string"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Notification not found",
+                        "content": {
+                            "text/html": {
+                                "schema": {
+                                    "type": "string"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "tags": []
+}
\ No newline at end of file