ZO-6181: sync updates from 'merkl' OpenAPI spec

docs/api/api.yaml

@@ -60,6 +60,7 @@ paths:
       security:
         - cookieAuthProduction: []
         - cookieAuthStaging: []
+      operationId: getBookmarks
       description:
         Returns list of bookmarks, optionally filtered by category.<br>
         Calling this endpoint without parameters returns all bookmarks.<br>
@@ -81,16 +82,14 @@ paths:
           content:
             application/json:
               schema:
-                anyOf:
-                  - $ref: "#/components/schemas/Bookmark"
-                  - $ref: "#/components/schemas/Category"
-          description: "Success"
+                $ref: "#/components/schemas/bookmark"
+          description: "Return list of bookmarks, optionally filtered by category"
         "400":
           description: "Something was wrong with the request to get bookmarks. Check the body for error messages."
         "401":
-          description: "Unauthorized to get bookmarks"
+          description: "Unauthorized to get filtered bookmarks"
         "503":
-          description: "Service unavailable to get bookmarks"
+          description: "Service unavailable to get filtered bookmarks"
     post:
       security:
         - cookieAuthProduction: []
@@ -100,7 +99,7 @@ paths:
       tags:
         - bookmarks
       requestBody:
-        description: Adds the given UUID at bookmarklist
+        description: Save new bookmark bookmarks endpoint, UUID is required.
         required: true
         content:
           application/json:
@@ -109,6 +108,9 @@ paths:
               properties:
                 uuid:
                   $ref: "#/components/schemas/UUID"
+              required:
+                - uuid
+              additionalProperties: false
       responses:
         "201":
           description: "Saved entry to bookmarks (201)"
@@ -141,7 +143,7 @@ paths:
           name: uuid
           required: false
           schema:
-            $ref: "#/components/schemas/UUIDFilter"
+            $ref: "#/components/schemas/uuidfilter"
           description: UUID of an article
       responses:
         "204":
@@ -174,12 +176,17 @@ paths:
                 items:
                   type: object
                   properties:
-                    ssoid:
+                    name:
+                      type: string
+                      example: artikel
+                    count:
                       type: integer
-                      example: 54
-                    uuid:
-                      $ref: "#/components/schemas/UUID"
-          description: "Success getting categories"
+                      example: 8
+                  required:
+                    - count
+                    - name
+                  additionalProperties: false
+          description: "Success getting each category name with count of its bookmarks"
         "400":
           description: "Something was wrong with the request to get categories. Check the body for error messages."
         "401":
@@ -706,13 +713,13 @@ components:
       items:
         $ref: "#/components/schemas/UUID"
 
-    UUIDFilter:
+    uuidfilter:
       type: string
       pattern: ^[eq\.]+(([a-f0-9]{8})(-[a-f0-9]{4}){3}(-[a-f0-9]{12})\\}?|[-a-z0-9/]+)$
       description: Postgrest equal filter function
       example: "eq.d995ba5a-a7fb-401a-bdc8-86cf2cbf0cda"
 
-    Bookmark:
+    bookmark:
       type: array
       description: Describes a bookmark item
       items:
@@ -726,13 +733,11 @@ components:
             example: 42
           uuid:
             $ref: "#/components/schemas/UUID"
-
-    Category:
-      description: Describes a filtered list of UUIDs
-      type: array
-      items:
-        type: string
-        example: "d995ba5a-a7fb-401a-bdc8-86cf2cbf0cda"
+        required:
+          - created
+          - ssoid
+          - uuid
+        additionalProperties: false
 
     BookmarkIds:
       type: object