files_versions: Add OpenAPI spec

Signed-off-by: jld3103 <[email protected]>

apps/files_versions/lib/Capabilities.php

@@ -42,6 +42,8 @@ public function __construct(
 
 	/**
 	 * Return this classes capabilities
+	 *
+	 * @return array{files: array{versioning: bool, version_labeling: bool, version_deletion: bool}}
 	 */
 	public function getCapabilities() {
 		$groupFolderInstalled = $this->appManager->isInstalled('groupfolders');

apps/files_versions/lib/Controller/PreviewController.php

@@ -69,11 +69,17 @@ public function __construct(
 	 * @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, \stdClass, array{}>
+	 *
+	 * 200: Preview returned
+	 * 400: Getting preview is not possible
+	 * 404: Preview not found
 	 */
 	public function getPreview(
 		string $file = '',
@@ -82,7 +88,7 @@ public function getPreview(
 		string $version = ''
 	) {
 		if ($file === '' || $version === '' || $x === 0 || $y === 0) {
-			return new DataResponse([], Http::STATUS_BAD_REQUEST);
+			return new DataResponse(new \stdClass(), Http::STATUS_BAD_REQUEST);
 		}
 
 		try {
@@ -93,9 +99,9 @@ public function getPreview(
 			$preview = $this->previewManager->getPreview($versionFile, $x, $y, true, IPreview::MODE_FILL, $versionFile->getMimetype());
 			return new FileDisplayResponse($preview, Http::STATUS_OK, ['Content-Type' => $preview->getMimeType()]);
 		} catch (NotFoundException $e) {
-			return new DataResponse([], Http::STATUS_NOT_FOUND);
+			return new DataResponse(new \stdClass(), Http::STATUS_NOT_FOUND);
 		} catch (\InvalidArgumentException $e) {
-			return new DataResponse([], Http::STATUS_BAD_REQUEST);
+			return new DataResponse(new \stdClass(), Http::STATUS_BAD_REQUEST);
 		}
 	}
 }

apps/files_versions/openapi.json

@@ -0,0 +1,147 @@
+{
+    "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": {
+                                    "type": "object",
+                                    "additionalProperties": true
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Preview not found",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "additionalProperties": true
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "tags": []
+}