Merge pull request #14235 from saraycp/staging_projects_get_post_endp…

…oints

Document GET and POST endpoints for staging projects

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

@@ -396,6 +396,8 @@ paths:
     $ref: 'paths/staging_project_name_backlog.yaml'
   /staging/{project_name}/excluded_requests:
     $ref: 'paths/staging_project_name_excluded_requests.yaml'
+  /staging/{project_name}/staging_projects:
+    $ref: 'paths/staging_project_name_staging_projects.yaml'
   /staging/{project_name}/workflow:
     $ref: 'paths/staging_project_name_workflow.yaml'
 

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

@@ -0,0 +1,86 @@
+type: object
+properties:
+  name:
+    type: string
+    example: openSUSE:Factory
+    xml:
+      attribute: true
+  state:
+    type: string
+    example: empty
+    xml:
+      attribute: true
+  staged_requests:
+    type: object
+    properties:
+      count:
+        type: integer
+        example: 0
+        xml:
+          attribute: true
+  untracked_requests:
+    type: object
+    properties:
+      count:
+        type: integer
+        example: 0
+        xml:
+          attribute: true
+  obsolete_requests:
+    type: object
+    properties:
+      count:
+        type: integer
+        example: 0
+        xml:
+          attribute: true
+  missing_reviews:
+    type: object
+    properties:
+      count:
+        type: integer
+        example: 0
+        xml:
+          attribute: true
+  building_repositories:
+    type: object
+    properties:
+      count:
+        type: integer
+        example: 0
+        xml:
+          attribute: true
+  broken_packages:
+    type: object
+    properties:
+      count:
+        type: integer
+        example: 0
+        xml:
+          attribute: true
+  checks:
+    type: object
+    properties:
+      count:
+        type: integer
+        example: 0
+        xml:
+          attribute: true
+  missing_checks:
+    type: object
+    properties:
+      count:
+        type: integer
+        example: 0
+        xml:
+          attribute: true
+  history:
+    type: object
+    properties:
+      count:
+        type: integer
+        example: 0
+        xml:
+          attribute: true
+xml:
+  name: staging_project

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

@@ -0,0 +1,8 @@
+type: object
+properties:
+  staging_project:
+    type: array
+    items:
+      $ref: 'staging_project.yaml'
+xml:
+  name: staging_projects

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

@@ -0,0 +1,9 @@
+type: object
+properties:
+  staging_project:
+    type: array
+    items:
+      type: string
+      example: openSUSE:Factory:Staging:C
+xml:
+  name: workflow

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

@@ -0,0 +1,148 @@
+get:
+  summary: List all the staging projects of a staging workflow.
+  description: |
+    List the staging projects of the staging workflow associated to the specified project.
+    Extra information can be requested by adding any combination of these parameters in the URL: `requests`, `status` and `history`.
+    - If `requests` is present, the output includes the staged, untracked and obsolete requests as well as missing reviews.
+    - If `status` is present, the output includes the overall state and the status xml (broken packages, missing reviews, checks, etc.)
+    - If `history` is present, the output includes the history of the staging project.
+  # Authentication is not required
+  parameters:
+    - $ref: '../components/parameters/project_name.yaml'
+    - name: requests
+      in: query
+      schema:
+        type: string
+        example:
+          1
+      description: |
+        "Set to `1` if you want to include the staged, untracked and obsolete requests as well as missing reviews, otherwise don't pass this query parameter."
+    - name: status
+      in: query
+      schema:
+        type: string
+        example:
+          1
+      description: |
+        "Set to `1` if you want to include the overall state and the status xml (broken packages, missing reviews, checks, etc.), otherwise don't pass this query parameter"
+    - name: history
+      in: query
+      schema:
+        type: string
+        example:
+          1
+      description: |
+        "Set to `1` if you want to include the history of the staging project, otherwise don't pass this query parameter."
+  responses:
+    '200':
+      description: OK. The request has succeeded.
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/staging/staging_projects.yaml'
+          examples:
+            Simple Result:
+              value:
+                staging_project:
+                  - name: openSUSE:Factory:Staging:A
+                  - name: openSUSE:Factory:Staging:B
+            Detailed Result:
+              value:
+                staging_project:
+                  name: openSUSE:Factory:Staging:A
+                  state: empty
+                  staged_requests:
+                    count: 0
+                  untracked_requests:
+                    count: 0
+                  obsolete_requests:
+                    count: 0
+                  missing_reviews:
+                    count: 0
+                  building_repositories:
+                    count: 0
+                  broken_packages:
+                    count: 0
+                  checks:
+                    count: 0
+                  missing_checks:
+                    count: 0
+                  history:
+                    count: 0
+    '404':
+      description: Not Found
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/api_response.yaml'
+          examples:
+            Project Without Staging Workflow:
+              value:
+                code: project_has_no_staging_workflow
+                summary: "No staging workflow for project 'project_name'"
+            Unknown Project:
+              value:
+                code: not_found
+                summary: "Project 'project_name' not found."
+  tags:
+    - Staging Workflow
+
+post:
+  summary: Create staging projects
+  description: Create staging projects on the staging workflow associated to the specified project
+  security:
+    - basic_authentication: []
+  parameters:
+    - $ref: '../components/parameters/project_name.yaml'
+  requestBody:
+    description: List of the names of the staging projects you want to add to the staging workflow
+    content:
+      application/xml; charset=utf-8:
+        schema:
+          $ref: '../components/schemas/staging/workflow_staging_projects.yaml'
+        examples:
+          Multiple Staging Projects:
+            value:
+                staging_project:
+                  - openSUSE:Factory:Staging:C
+                  - openSUSE:Factory:Staging:D
+  responses:
+    '200':
+      $ref: '../components/responses/succeeded.yaml'
+    '401':
+      $ref: '../components/responses/unauthorized.yaml'
+    '400':
+      description: |
+        Bad Request.
+
+        XML Schema used for body validation: [status.xsd](../schema/status.xsd).
+      content:
+        application/xml; charset=utf-8:
+          schema:
+            $ref: '../components/schemas/api_response.yaml'
+          examples:
+            Invalid Project Name:
+              value:
+                code: invalid_request
+                summary: 'Staging Projects for package_name failed: Project "0": Name is illegal.'
+            Already Assigned:
+              value:
+                code: invalid_request
+                summary: 'Staging Projects for project_name failed: Project "project_name": is already assigned to a staging workflow.'
+    '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
+                summary: "Project project_name doesn't have an associated Staging Workflow"
+            Unknown Project:
+              value:
+                code: not_found
+                summary: "Project 'project_name' not found."
+  tags:
+    - Staging Workflow