files_versions: Add OpenAPI spec

Signed-off-by: jld3103 <jld3103yt@gmail.com>

diff --git a/apps/files_versions/lib/Capabilities.php b/apps/files_versions/lib/Capabilities.php
index b5861db89376f6b726fa89667e7948d1ff22c817..7091f9c4676e95e2d8a9e728a58baddfffdcdfc5 100644 (file)
--- 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 0e625dc21399784253898fb93dd127dee44746bc..1365e7e50faf43c1af77f2ab6d9b173a569cce91 100644 (file)
--- 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 (file)
index 0000000..2ff4dcc
--- /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