From 2af0d2c5ff2439c5a473af07b95139cc6cb11db0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ciar=C3=A1n=20Ainsworth?= <ciaranainsworth@proton.me>
Date: Fri, 17 Nov 2023 15:39:15 +0100
Subject: [PATCH] feat(docs): add more collection schema updates

---
 docs/schema.yml                   | 69 +++++++++++++++++++++++++------
 docs/specs/collections/schema.yml | 22 +++++++++-
 2 files changed, 77 insertions(+), 14 deletions(-)

diff --git a/docs/schema.yml b/docs/schema.yml
index afca3812c..34f2f8529 100644
--- a/docs/schema.yml
+++ b/docs/schema.yml
@@ -61,22 +61,20 @@ paths:
       summary: "Add a new collection"
       description: "Add a new collection to the server"
       operationId: postCollection
+      requestBody:
+        description: "The new metadata of the collection"
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "specs/collections/schema.yml#/NewCollection"
       responses:
-        "200":
-          description: Successful operation
+        "201":
+          description: Created
           content:
             application/json:
               schema:
-                allOf:
-                  - $ref: "#/components/schemas/Pagination"
-                  - type: object
-                    required:
-                      - results
-                    properties:
-                      results:
-                        type: array
-                        items:
-                          $ref: "specs/collections/schema.yml#/Collection"
+                $ref: "specs/collections/schema.yml#/SimpleCollection"
   /api/v2/collections/{guid}:
     get:
       tags:
@@ -99,6 +97,51 @@ paths:
             application/json:
               schema:
                 $ref: "specs/collections/schema.yml#/Collection"
+    patch:
+      tags:
+        - Collections
+      summary: "Update the metadata of a collection"
+      description: "Change metadata and details about a specific collection"
+      operationId: patchCollection
+      parameters:
+        - name: guid
+          in: path
+          required: true
+          description: The GUID of the collection
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        description: "The new metadata of the collection"
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "specs/collections/schema.yml#/UpdateCollection"
+      responses:
+        "202":
+          description: Accepted
+          content:
+            application/json:
+              schema:
+                $ref: "specs/collections/schema.yml#/SimpleCollection"
+    delete:
+      tags:
+        - Collections
+      summary: "Delete a specific collection"
+      description: "Delete a collection. This does not delete the associated uploads."
+      operationId: deleteCollection
+      parameters:
+        - name: guid
+          in: path
+          required: true
+          description: The GUID of the collection
+          schema:
+            type: string
+            format: uuid
+      responses:
+        "200":
+          description: Successful operation
   /api/v2/instance/nodeinfo/2.1:
     get:
       tags:
@@ -249,7 +292,7 @@ paths:
             schema:
               $ref: "#/components/schemas/CreateRelease"
       responses:
-        "202":
+        "201":
           description: Created
           content:
             application/json:
diff --git a/docs/specs/collections/schema.yml b/docs/specs/collections/schema.yml
index a6342b3f3..1b97a1617 100644
--- a/docs/specs/collections/schema.yml
+++ b/docs/specs/collections/schema.yml
@@ -28,6 +28,26 @@ Collection:
         description:
           type: string
           description: "The user-defined description of the collection"
-        items:
+        recordingCount:
           type: integer
           description: "The total number of items in the collection"
+NewCollection:
+  type: object
+  required:
+    - name
+  properties:
+    name:
+      type: string
+      description: "The new name for the collection"
+    description:
+      type: string
+      description: "The new description for the collection"
+UpdateCollection:
+  type: object
+  properties:
+    name:
+      type: string
+      description: "The new name for the collection"
+    description:
+      type: string
+      description: "The new description for the collection"