Add endpoints, services, and security controls for particle file management, including save and download APIs.

2025-06-29 03:15:39 +02:00
parent c72703ea32
commit 7fc25f46f3
6 changed files with 402 additions and 0 deletions
@@ -0,0 +1,176 @@
+components:
+  parameters:
+    Filename:
+      name: filename
+      in: path
+      required: true
+      schema:
+        type: string
+        description: The name of the file
+    Secret:
+      name: Authorization
+      in: header
+      required: true
+      schema:
+        type: string
+        description: Secret
+  schemas:
+    FileData:
+      type: object
+      required:
+        - content
+      properties:
+        content:
+          type: string
+          format: binary
+          description: The content of the file
+
+SaveFile:
+  post:
+    tags:
+      - particles
+    summary: Save a file
+    description: Save a file to the server (requires authorization)
+    operationId: saveFile
+    security:
+      - bearerAuth: []
+    parameters:
+      - $ref: '#/components/parameters/Filename'
+    requestBody:
+      required: true
+      content:
+        multipart/form-data:
+          schema:
+            $ref: '#/components/schemas/FileData'
+    responses:
+      '200':
+        description: File saved successfully
+      '401':
+        description: Unauthorized - Invalid or missing token
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+      '403':
+        description: Forbidden - Insufficient permissions
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+      default:
+        description: Unexpected error
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+
+SaveFileForUser:
+  post:
+    tags:
+      - particles
+    summary: Save a file for a specific user
+    description: Save a file to the server for a specific user (requires head_mod permission)
+    operationId: saveFileForUser
+    security:
+      - bearerAuth: []
+    parameters:
+      - $ref: '../generic/parameters.yml#/components/parameters/Uuid'
+      - $ref: '#/components/parameters/Filename'
+    requestBody:
+      required: true
+      content:
+        multipart/form-data:
+          schema:
+            $ref: '#/components/schemas/FileData'
+    responses:
+      '200':
+        description: File saved successfully
+      '401':
+        description: Unauthorized - Invalid or missing token
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+      '403':
+        description: Forbidden - Insufficient permissions
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+      default:
+        description: Unexpected error
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+
+DownloadFile:
+  get:
+    tags:
+      - particles
+    summary: Download a file
+    description: Download a file from the server using a secret key
+    operationId: downloadFile
+    parameters:
+      - $ref: '#/components/parameters/Secret'
+      - $ref: '#/components/parameters/Filename'
+    responses:
+      '200':
+        description: File downloaded successfully
+        content:
+          application/octet-stream:
+            schema:
+              type: string
+              format: binary
+      '404':
+        description: File not found
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+      default:
+        description: Unexpected error
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+
+DownloadFileForUser:
+  get:
+    tags:
+      - particles
+    summary: Download a file for a specific user
+    description: Download a file from the server for a specific user (requires authorization)
+    operationId: downloadFileForUser
+    security:
+      - bearerAuth: []
+    parameters:
+      - $ref: '#/components/parameters/Secret'
+      - $ref: '../generic/parameters.yml#/components/parameters/Uuid'
+      - $ref: '#/components/parameters/Filename'
+    responses:
+      '200':
+        description: File downloaded successfully
+        content:
+          application/octet-stream:
+            schema:
+              type: string
+              format: binary
+      '401':
+        description: Unauthorized - Invalid or missing token
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+      '404':
+        description: File not found
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'
+      default:
+        description: Unexpected error
+        content:
+          application/json:
+            schema:
+              $ref: '../generic/errors.yml#/components/schemas/ApiError'