Merge pull request #185 from qase-tms/add-run-update-external-issue-specs

feat: add endpoint to update external issue links for test runs

Author: abelharisov

testops-api/v1/parameters/extend/Runs.yaml

@@ -1,6 +1,6 @@
 name: include
 in: query
 description: |
-  Include a list of related entities IDs into response. Should be separated by comma. Possible values: cases, defects
+  Include a list of related entities IDs into response. Should be separated by comma. Possible values: cases, defects, external_issue
 schema:
   type: string

testops-api/v1/paths/runs_external_issue.yaml

@@ -0,0 +1,39 @@
+post:
+  operationId: run-update-external-issue
+  tags: [ runs ]
+  summary: Update external issues for runs
+  description: |
+    This method allows you to update links between test runs and external issues (such as Jira tickets).
+
+    You can use this endpoint to:
+    - Link test runs to external issues by providing the external issue identifier (e.g., "PROJ-1234")
+    - Update existing links by providing a new external issue identifier
+    - Remove existing links by setting the external_issue field to null
+
+    **Important**: Each test run can have only one link with an external issue. If a test run already has an external issue link, providing a new external_issue value will replace the existing link.
+
+    The endpoint supports both Jira Cloud and Jira Server integrations. Each request can update multiple test run links in a single operation.
+
+  parameters:
+    - $ref: '../parameters/Code.yaml'
+
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '../schemas/Run.external_issues.yaml'
+
+  responses:
+    200:
+      description: OK.
+    400:
+      description: Bad Request.
+    401:
+      description: Unauthorized.
+    403:
+      description: Forbidden.
+    404:
+      description: Not Found.
+    429:
+      description: Too Many Requests.

testops-api/v1/schemas/Run.external_issues.yaml

@@ -0,0 +1,26 @@
+type: object
+properties:
+  type:
+    type: string
+    enum:
+      - jira-cloud
+      - jira-server
+  links:
+    type: array
+    description: Array of external issue links. Each test run (run_id) can have only one external issue link.
+    items:
+      type: object
+      properties:
+        run_id:
+          type: integer
+          format: int64
+        external_issue:
+          type: string
+          nullable: true
+          minLength: 1
+          description: An external issue identifier, e.g. "PROJ-1234". Or null if you want to remove the link.
+      required:
+        - run_id
+required:
+  - type
+  - links

testops-api/v1/schemas/Run.yaml

@@ -110,3 +110,14 @@ properties:
     items:
       type: integer
       format: int64
+  external_issue:
+    type: object
+    nullable: true
+    properties:
+      id:
+        type: string
+      type:
+        type: string
+      link:
+        type: string
+        format: uri

testops-api/v1/src.yaml

@@ -102,6 +102,8 @@ paths:
     $ref: './paths/result_id_hash.yaml'
   /run/{code}:
     $ref: './paths/runs.yaml'
+  /run/{code}/external-issue:
+    $ref: './paths/runs_external_issue.yaml'
   /run/{code}/{id}:
     $ref: './paths/run.yaml'
   /run/{code}/{id}/public: