Merge pull request #14213 from saraycp/staging_backlog_endpoint

Document staging backlog endpoint with OpenAPI

src/api/public/apidocs-new/OBS-v2.10.50.yaml

@@ -388,6 +388,8 @@ paths:
     $ref: 'paths/source_project_name_package_name_binary_filename_attribute.yaml'
 
   # Staging Workflow
+  /staging/{project_name}/backlog:
+    $ref: 'paths/staging_project_name_backlog.yaml'
   /staging/{staging_workflow_project}/workflow:
     $ref: 'paths/staging_staging_workflow_project_workflow.yaml'
 

src/api/public/apidocs-new/components/schemas/staging/backlog.yaml

@@ -0,0 +1,44 @@
+type: object
+properties:
+  request:
+    type: array
+    items:
+      type: object
+      properties:
+        id:
+          type: integer
+          example: 42
+          xml:
+            attribute: true
+        creator:
+          type: string
+          example: foo-user
+          xml:
+            attribute: true
+        type:
+          type: string
+          example: submit
+          xml:
+            attribute: true
+        state:
+          type: string
+          example: review
+          xml:
+            attribute: true
+        package:
+          type: string
+          example: 'hello_world'
+          xml:
+            attribute: true
+        superseded_by:
+          type: integer
+          example: 43
+          xml:
+            attribute: true
+        updated:
+          type: string
+          example: '2023-04-24T08:34:39Z'
+          xml:
+            attribute: true
+xml:
+  name: backlog

src/api/public/apidocs-new/paths/staging_project_name_backlog.yaml

@@ -0,0 +1,34 @@
+get:
+  summary: List the requests in the staging backlog.
+  description: |
+    List the requests that can be assigned to the staging project (backlog).
+  security:
+    - basic_authentication: []
+  parameters:
+    - $ref: '../components/parameters/project_name.yaml'
+  responses:
+    '200':
+      description: List of request in the staging backlog.
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/staging/backlog.yaml'
+    '401':
+      $ref: '../components/responses/unauthorized.yaml'
+    '404':
+      description: Not Found
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/api_response.yaml'
+          examples:
+            project_without_staging_workflow:
+              value:
+                code: not_found
+                sumary: "Project project_name doesn't have an associated Staging Workflow"
+            Unknown Project:
+              value:
+                code: unknown_project
+                summary: "Project not found: <some project>."
+  tags:
+    - Staging Workflow