From 3dff41786d9a00a6dce81fee4345b0ebd374d06c Mon Sep 17 00:00:00 2001
From: jld3103 <jld3103yt@gmail.com>
Date: Wed, 14 Jun 2023 16:42:04 +0200
Subject: [PATCH] files_versions: Add OpenAPI spec

Signed-off-by: jld3103 <jld3103yt@gmail.com>
---
 apps/files_versions/lib/Capabilities.php      |   2 +
 .../lib/Controller/PreviewController.php      |  16 +-
 apps/files_versions/openapi.json              | 141 ++++++++++++++++++
 3 files changed, 154 insertions(+), 5 deletions(-)
 create mode 100644 apps/files_versions/openapi.json

diff --git a/apps/files_versions/lib/Capabilities.php b/apps/files_versions/lib/Capabilities.php
index b5861db8937..7091f9c4676 100644
--- a/apps/files_versions/lib/Capabilities.php
+++ b/apps/files_versions/lib/Capabilities.php
@@ -42,6 +42,8 @@ class Capabilities implements ICapability {
 
 	/**
 	 * Return this classes capabilities
+	 *
+	 * @return array{files: array{versioning: bool, version_labeling: bool, version_deletion: bool}}
 	 */
 	public function getCapabilities() {
 		return [
diff --git a/apps/files_versions/lib/Controller/PreviewController.php b/apps/files_versions/lib/Controller/PreviewController.php
index 0e625dc2139..1365e7e50fa 100644
--- a/apps/files_versions/lib/Controller/PreviewController.php
+++ b/apps/files_versions/lib/Controller/PreviewController.php
@@ -69,11 +69,17 @@ class PreviewController extends Controller {
 	 * @NoAdminRequired
 	 * @NoCSRFRequired
 	 *
-	 * @param string $file
-	 * @param int $x
-	 * @param int $y
-	 * @param string $version
-	 * @return DataResponse|FileDisplayResponse
+	 * Get the preview for a file version
+	 *
+	 * @param string $file Path of the file
+	 * @param int $x Width of the preview
+	 * @param int $y Height of the preview
+	 * @param string $version Version of the file to get the preview for
+	 * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 *
+	 * 200: Preview returned
+	 * 400: Getting preview is not possible
+	 * 404: Preview not found
 	 */
 	public function getPreview(
 		string $file = '',
diff --git a/apps/files_versions/openapi.json b/apps/files_versions/openapi.json
new file mode 100644
index 00000000000..2ff4dcc2035
--- /dev/null
+++ b/apps/files_versions/openapi.json
@@ -0,0 +1,141 @@
+{
+    "openapi": "3.0.3",
+    "info": {
+        "title": "files_versions",
+        "version": "0.0.1",
+        "description": "This application automatically maintains older versions of files that are changed.",
+        "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": [
+                            "versioning",
+                            "version_labeling",
+                            "version_deletion"
+                        ],
+                        "properties": {
+                            "versioning": {
+                                "type": "boolean"
+                            },
+                            "version_labeling": {
+                                "type": "boolean"
+                            },
+                            "version_deletion": {
+                                "type": "boolean"
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "paths": {
+        "/index.php/apps/files_versions/preview": {
+            "get": {
+                "operationId": "preview-get-preview",
+                "summary": "Get the preview for a file version",
+                "tags": [
+                    "preview"
+                ],
+                "security": [
+                    {
+                        "bearer_auth": []
+                    },
+                    {
+                        "basic_auth": []
+                    }
+                ],
+                "parameters": [
+                    {
+                        "name": "file",
+                        "in": "query",
+                        "description": "Path of the file",
+                        "schema": {
+                            "type": "string",
+                            "default": ""
+                        }
+                    },
+                    {
+                        "name": "x",
+                        "in": "query",
+                        "description": "Width of the preview",
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64",
+                            "default": 44
+                        }
+                    },
+                    {
+                        "name": "y",
+                        "in": "query",
+                        "description": "Height of the preview",
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64",
+                            "default": 44
+                        }
+                    },
+                    {
+                        "name": "version",
+                        "in": "query",
+                        "description": "Version of the file to get the preview for",
+                        "schema": {
+                            "type": "string",
+                            "default": ""
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Preview returned",
+                        "content": {
+                            "*/*": {
+                                "schema": {
+                                    "type": "string",
+                                    "format": "binary"
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Getting preview is not possible",
+                        "content": {
+                            "application/json": {
+                                "schema": {}
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Preview not found",
+                        "content": {
+                            "application/json": {
+                                "schema": {}
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "tags": []
+}
\ No newline at end of file
-- 
2.39.5