Add POST /api/teleporter to upload and install backed up configuration

Signed-off-by: DL6ER <dl6er@dl6er.de>

src/api/docs/content/specs/teleporter.yaml

@@ -8,7 +8,8 @@ components:
           - "Pi-hole configuration"
         operationId: "get_teleporter"
         description: |
-          Request an archived copy of your Pi-hole's current configuration
+          Request an archived copy of your Pi-hole's current configuration.
+          Authentication via header or cookie is required for the endpoint.
         responses:
           '200':
             description: OK
@@ -22,4 +23,79 @@ components:
             content:
               application/json:
                 schema:
-                  $ref: 'common.yaml#/components/errors/unauthorized'
+                  $ref: 'common.yaml#/components/errors/unauthorized'
+      post:
+        summary: Import Pi-hole settings
+        tags:
+          - "Pi-hole configuration"
+        operationId: "post_teleporter"
+        description: |
+          Upload a Pi-hole Teleporter archive to (partially) restore from it. Note that this will overwrite your current configuration.
+          Authentication via header or cookie is required for the endpoint.
+        requestBody:
+          content:
+            multipart/form-data:
+              schema:
+                properties:
+                  file:
+                    type: string
+                    format: binary
+        responses:
+          '200':
+            description: OK
+            content:
+              application/json:
+                schema:
+                  $ref: 'teleporter.yaml#/components/schemas/teleporter/post'
+                examples:
+                  teleporter:
+                    $ref: 'teleporter.yaml#/components/examples/teleporter'
+          '400':
+            description: Bad request
+            content:
+              application/json:
+                schema:
+                  $ref: 'teleporter.yaml#/components/errors/invalid_zip'
+          '401':
+            description: Unauthorized
+            content:
+              application/json:
+                schema:
+                  $ref: 'common.yaml#/components/errors/unauthorized'
+  schemas:
+    teleporter:
+      post:
+        type: object
+        properties:
+          processed:
+            type: array
+            items:
+              type: string
+  errors:
+    invalid_zip:
+      type: object
+      description: Invalid ZIP archive uploaded
+      properties:
+        error:
+          type: object
+          properties:
+            key:
+              type: string
+              description: "Machine-readable error type"
+              example: "invalid_zip"
+            message:
+              type: string
+              description: "Human-readable error message"
+              example: "Invalid ZIP file uploaded"
+            hint:
+              type: string
+              nullable: true
+              description: "No additional data available"
+              example: null
+
+  examples:
+    teleporter:
+      value:
+        teleporter:
+          - a
+          - b