generate openapi specs

Signed-off-by: Julien Veyssier <[email protected]>
nextcloud · Jan 27, 2025 · a19dbe0 · a19dbe0
1 parent c010255
commit a19dbe0
Show file tree

Hide file tree

Showing 3 changed files with 139 additions and 3 deletions.
diff --git a/lib/Controller/AssistantApiController.php b/lib/Controller/AssistantApiController.php
@@ -20,6 +20,7 @@
 use OCP\AppFramework\Http\RedirectResponse;
 use OCP\AppFramework\OCSController;
 use OCP\DB\Exception;
+use OCP\Files\File;
 use OCP\Files\GenericFileException;
 use OCP\Files\NotPermittedException;
 use OCP\IL10N;
@@ -279,10 +280,12 @@ public function getOutputFilePreview(int $ocpTaskId, int $fileId, ?int $x = 100,
 			}
 
 			if ($preview['type'] === 'file') {
+				/** @var File $file */
+				$file = $preview['type'];
 				$response = new DataDownloadResponse(
-					$preview['file']->getContent(),
+					$file->getContent(),
 					$ocpTaskId . '-' . $fileId . '-preview',
-					$preview['file']->getMimeType()
+					$file->getMimeType()
 				);
 				$response->cacheFor(60 * 60 * 24, false, true);
 				return $response;

diff --git a/openapi.json b/openapi.json
@@ -1267,7 +1267,7 @@
         "/ocs/v2.php/apps/assistant/api/{apiVersion}/task/{ocpTaskId}/output-file/{fileId}/preview": {
             "get": {
                 "operationId": "assistant_api-get-output-file-preview",
-                "summary": "Get output file preview",
+                "summary": "Get task output file preview",
                 "description": "Generate and get a preview of a task output file",
                 "tags": [
                     "assistant_api"
@@ -1313,6 +1313,28 @@
                             "format": "int64"
                         }
                     },
+                    {
+                        "name": "x",
+                        "in": "query",
+                        "description": "Optional preview width in pixels",
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64",
+                            "nullable": true,
+                            "default": 100
+                        }
+                    },
+                    {
+                        "name": "y",
+                        "in": "query",
+                        "description": "Optional preview height in pixels",
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64",
+                            "nullable": true,
+                            "default": 100
+                        }
+                    },
                     {
                         "name": "OCS-APIRequest",
                         "in": "header",
@@ -1378,6 +1400,111 @@
                     }
                 }
             }
+        },
+        "/ocs/v2.php/apps/assistant/api/{apiVersion}/task/{ocpTaskId}/output-file/{fileId}/download": {
+            "get": {
+                "operationId": "assistant_api-get-output-file",
+                "summary": "Get task output file",
+                "description": "Get a real task output file",
+                "tags": [
+                    "assistant_api"
+                ],
+                "security": [
+                    {
+                        "bearer_auth": []
+                    },
+                    {
+                        "basic_auth": []
+                    }
+                ],
+                "parameters": [
+                    {
+                        "name": "apiVersion",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string",
+                            "enum": [
+                                "v1"
+                            ],
+                            "default": "v1"
+                        }
+                    },
+                    {
+                        "name": "ocpTaskId",
+                        "in": "path",
+                        "description": "The task ID",
+                        "required": true,
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64"
+                        }
+                    },
+                    {
+                        "name": "fileId",
+                        "in": "path",
+                        "description": "The task output file ID",
+                        "required": true,
+                        "schema": {
+                            "type": "integer",
+                            "format": "int64"
+                        }
+                    },
+                    {
+                        "name": "OCS-APIRequest",
+                        "in": "header",
+                        "description": "Required to be true for the API request to pass",
+                        "required": true,
+                        "schema": {
+                            "type": "boolean",
+                            "default": true
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "The file preview has been generated and is returned",
+                        "content": {
+                            "*/*": {
+                                "schema": {
+                                    "type": "string",
+                                    "format": "binary"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "The output file is not found",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "required": [
+                                        "ocs"
+                                    ],
+                                    "properties": {
+                                        "ocs": {
+                                            "type": "object",
+                                            "required": [
+                                                "meta",
+                                                "data"
+                                            ],
+                                            "properties": {
+                                                "meta": {
+                                                    "$ref": "#/components/schemas/OCSMeta"
+                                                },
+                                                "data": {
+                                                    "type": "string"
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
         }
     },
     "tags": []

diff --git a/tests/psalm-baseline.xml b/tests/psalm-baseline.xml
@@ -5,6 +5,12 @@
 -->
 <files psalm-version="5.26.1@d747f6500b38ac4f7dfc5edbcae6e4b637d7add0">
   <file src="lib/Controller/AssistantApiController.php">
+    <InvalidReturnStatement>
+      <code><![CDATA[$response]]></code>
+    </InvalidReturnStatement>
+    <InvalidReturnType>
+      <code><![CDATA[DataDownloadResponse<Http::STATUS_OK, string, array{}>|DataResponse<Http::STATUS_NOT_FOUND, '', array{}>]]></code>
+    </InvalidReturnType>
     <LessSpecificReturnStatement>
       <code><![CDATA[new DataResponse(['tasks' => $serializedTasks])]]></code>
       <code><![CDATA[new DataResponse(['types' => $taskTypes])]]></code>