From 450726cfd2ab318bc36604b82cd622f282122d39 Mon Sep 17 00:00:00 2001
From: jld3103 <jld3103yt@gmail.com>
Date: Thu, 29 Jun 2023 07:48:16 +0200
Subject: [PATCH] comments: Add OpenAPI spec

Signed-off-by: jld3103 <jld3103yt@gmail.com>
---
 apps/comments/lib/Capabilities.php            |   3 +
 .../Controller/NotificationsController.php    |  13 ++-
 apps/comments/openapi.json                    | 103 ++++++++++++++++++
 3 files changed, 117 insertions(+), 2 deletions(-)
 create mode 100644 apps/comments/openapi.json

diff --git a/apps/comments/lib/Capabilities.php b/apps/comments/lib/Capabilities.php
index ba5d2a2086b25..597f248412c7d 100644
--- a/apps/comments/lib/Capabilities.php
+++ b/apps/comments/lib/Capabilities.php
@@ -28,6 +28,9 @@
 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 41a9541a68409..e286d1d279b0c 100644
--- a/apps/comments/lib/Controller/NotificationsController.php
+++ b/apps/comments/lib/Controller/NotificationsController.php
@@ -27,7 +27,7 @@
 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;
@@ -73,8 +73,17 @@ public function __construct(
 	/**
 	 * @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 0000000000000..9dbf618a4c726
--- /dev/null
+++ b/apps/comments/openapi.json
@@ -0,0 +1,103 @@
+{
+    "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": [
+        {
+            "name": "notifications",
+            "description": "Class NotificationsController"
+        }
+    ]
+}
\ No newline at end of file