Update SearchFlakyTests endpoint documentation (#3698)

Co-authored-by: ci.datadog-api-spec <packages@datadoghq.com>

Author: api-clients-generation-pipeline[bot]

.generator/schemas/v2/openapi.yaml

@@ -26664,9 +26664,18 @@ components:
             Includes state transitions like new -> quarantined -> fixed, along with the associated commit SHA when available.
           example:
             - commit_sha: abc123def456
+              policy_id: ftm_policy.quarantine.failure_rate
+              policy_meta:
+                config:
+                  failure_rate: 0.1
+                  required_runs: 100
+                failure_rate: 0.25
+                total_runs: 200
               status: quarantined
               timestamp: 1704067200000
             - commit_sha: ""
+              policy_id: unknown
+              policy_meta:
               status: new
               timestamp: 1703980800000
           items:
@@ -26736,6 +26745,11 @@ components:
           description: The commit SHA associated with this status change. Will be an empty string if the commit SHA is not available.
           example: abc123def456
           type: string
+        policy_id:
+          $ref: "#/components/schemas/FlakyTestHistoryPolicyId"
+        policy_meta:
+          $ref: "#/components/schemas/FlakyTestHistoryPolicyMeta"
+          nullable: true
         status:
           description: The test status at this point in history.
           example: quarantined
@@ -26750,6 +26764,131 @@ components:
         - commit_sha
         - timestamp
       type: object
+    FlakyTestHistoryPolicyId:
+      description: The policy that triggered this status change.
+      enum:
+        - ftm_policy.manual
+        - ftm_policy.fixed
+        - ftm_policy.disable.failure_rate
+        - ftm_policy.disable.branch_flake
+        - ftm_policy.disable.days_active
+        - ftm_policy.quarantine.failure_rate
+        - ftm_policy.quarantine.branch_flake
+        - ftm_policy.quarantine.days_active
+        - unknown
+      example: ftm_policy.quarantine.failure_rate
+      nullable: false
+      type: string
+      x-enum-varnames:
+        - MANUAL
+        - FIXED
+        - DISABLE_FAILURE_RATE
+        - DISABLE_BRANCH_FLAKE
+        - DISABLE_DAYS_ACTIVE
+        - QUARANTINE_FAILURE_RATE
+        - QUARANTINE_BRANCH_FLAKE
+        - QUARANTINE_DAYS_ACTIVE
+        - UNKNOWN
+    FlakyTestHistoryPolicyMeta:
+      description: Metadata about the policy that triggered this status change.
+      properties:
+        branches:
+          description: Branches where the test was flaky at the time of the status change.
+          example: ["main", "develop"]
+          items:
+            type: string
+          nullable: true
+          type: array
+        config:
+          $ref: "#/components/schemas/FlakyTestHistoryPolicyMetaConfig"
+          nullable: true
+        days_active:
+          description: The number of days the test has been active at the time of the status change.
+          example: 15
+          format: int32
+          maximum: 2147483647
+          nullable: true
+          type: integer
+        days_without_flake:
+          description: The number of days since the test last exhibited flakiness.
+          example: 30
+          format: int32
+          maximum: 2147483647
+          nullable: true
+          type: integer
+        failure_rate:
+          description: The failure rate of the test at the time of the status change.
+          example: 0.25
+          format: double
+          maximum: 1
+          minimum: 0
+          nullable: true
+          type: number
+        state:
+          description: The previous state of the test.
+          example: quarantined
+          nullable: true
+          type: string
+        total_runs:
+          description: The total number of test runs at the time of the status change.
+          example: 200
+          format: int32
+          maximum: 2147483647
+          nullable: true
+          type: integer
+      type: object
+    FlakyTestHistoryPolicyMetaConfig:
+      description: Configuration parameters of the policy that triggered this status change.
+      properties:
+        branches:
+          description: The branches considered by the policy.
+          example: ["main"]
+          items:
+            type: string
+          nullable: true
+          type: array
+        days_active:
+          description: The number of days a test must have been active for the policy to trigger.
+          example: 30
+          format: int32
+          maximum: 2147483647
+          nullable: true
+          type: integer
+        failure_rate:
+          description: The failure rate threshold for the policy to trigger.
+          example: 0.7
+          format: double
+          maximum: 1
+          minimum: 0
+          nullable: true
+          type: number
+        forget_branches:
+          description: Branches excluded from the policy evaluation.
+          example: ["release"]
+          items:
+            type: string
+          nullable: true
+          type: array
+        required_runs:
+          description: The minimum number of test runs required for the policy to trigger.
+          example: 100
+          format: int32
+          maximum: 2147483647
+          nullable: true
+          type: integer
+        state:
+          description: The target state the policy transitions the test from.
+          example: quarantined
+          nullable: true
+          type: string
+        test_services:
+          description: Test services excluded from the policy evaluation.
+          example: ["my-service"]
+          items:
+            type: string
+          nullable: true
+          type: array
+      type: object
     FlakyTestPipelineStats:
       description: CI pipeline related statistics for the flaky test. This information is only available if test runs are associated with CI pipeline events from CI Visibility.
       properties:
@@ -26829,6 +26968,14 @@ components:
     FlakyTestsSearchFilter:
       description: Search filter settings.
       properties:
+        include_history:
+          default: false
+          description: |-
+            Whether to include the status change history for each flaky test in the response.
+            When set to true, each test will include a `history` array with chronological status changes.
+            Defaults to false.
+          example: true
+          type: boolean
         query:
           default: "*"
           description: |-
@@ -26874,14 +27021,6 @@ components:
       properties:
         filter:
           $ref: "#/components/schemas/FlakyTestsSearchFilter"
-        include_history:
-          default: false
-          description: |-
-            Whether to include the status change history for each flaky test in the response.
-            When set to true, each test will include a `history` array with chronological status changes.
-            Defaults to false.
-          example: true
-          type: boolean
         page:
           $ref: "#/components/schemas/FlakyTestsSearchPageOptions"
         sort:

examples/v2/test-optimization/SearchFlakyTests.java

@@ -27,11 +27,11 @@ public static void main(String[] args) {
                         new FlakyTestsSearchRequestAttributes()
                             .filter(
                                 new FlakyTestsSearchFilter()
+                                    .includeHistory(true)
                                     .query(
                                         """
 flaky_test_state:active @git.repository.id_v2:"github.com/datadog/shopist"
 """))
-                            .includeHistory(true)
                             .page(
                                 new FlakyTestsSearchPageOptions()
                                     .cursor(

examples/v2/test-optimization/SearchFlakyTests_1224086727.java

@@ -27,11 +27,11 @@ public static void main(String[] args) {
                         new FlakyTestsSearchRequestAttributes()
                             .filter(
                                 new FlakyTestsSearchFilter()
+                                    .includeHistory(true)
                                     .query(
                                         """
 flaky_test_state:active @git.repository.id_v2:"github.com/datadog/shopist"
 """))
-                            .includeHistory(true)
                             .page(
                                 new FlakyTestsSearchPageOptions()
                                     .cursor(

examples/v2/test-optimization/SearchFlakyTests_209064879.java

@@ -30,10 +30,10 @@ public static void main(String[] args) {
                                     .query(
                                         """
 flaky_test_state:active @git.repository.id_v2:"github.com/datadog/shopist"
-"""))
+""")
+                                    .includeHistory(true))
                             .page(new FlakyTestsSearchPageOptions().limit(10L))
-                            .sort(FlakyTestsSearchSort.FQN_ASCENDING)
-                            .includeHistory(true))
+                            .sort(FlakyTestsSearchSort.FQN_ASCENDING))
                     .type(FlakyTestsSearchRequestDataType.SEARCH_FLAKY_TESTS_REQUEST));
 
     try {

src/main/java/com/datadog/api/client/v2/model/FlakyTestHistory.java

@@ -20,6 +20,8 @@
 /** A single history entry representing a status change for a flaky test. */
 @JsonPropertyOrder({
   FlakyTestHistory.JSON_PROPERTY_COMMIT_SHA,
+  FlakyTestHistory.JSON_PROPERTY_POLICY_ID,
+  FlakyTestHistory.JSON_PROPERTY_POLICY_META,
   FlakyTestHistory.JSON_PROPERTY_STATUS,
   FlakyTestHistory.JSON_PROPERTY_TIMESTAMP
 })
@@ -30,6 +32,12 @@ public class FlakyTestHistory {
   public static final String JSON_PROPERTY_COMMIT_SHA = "commit_sha";
   private String commitSha;
 
+  public static final String JSON_PROPERTY_POLICY_ID = "policy_id";
+  private FlakyTestHistoryPolicyId policyId;
+
+  public static final String JSON_PROPERTY_POLICY_META = "policy_meta";
+  private FlakyTestHistoryPolicyMeta policyMeta;
+
   public static final String JSON_PROPERTY_STATUS = "status";
   private String status;
 
@@ -69,6 +77,53 @@ public void setCommitSha(String commitSha) {
     this.commitSha = commitSha;
   }
 
+  public FlakyTestHistory policyId(FlakyTestHistoryPolicyId policyId) {
+    this.policyId = policyId;
+    this.unparsed |= !policyId.isValid();
+    return this;
+  }
+
+  /**
+   * The policy that triggered this status change.
+   *
+   * @return policyId
+   */
+  @jakarta.annotation.Nullable
+  @JsonProperty(JSON_PROPERTY_POLICY_ID)
+  @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS)
+  public FlakyTestHistoryPolicyId getPolicyId() {
+    return policyId;
+  }
+
+  public void setPolicyId(FlakyTestHistoryPolicyId policyId) {
+    if (!policyId.isValid()) {
+      this.unparsed = true;
+    }
+    this.policyId = policyId;
+  }
+
+  public FlakyTestHistory policyMeta(FlakyTestHistoryPolicyMeta policyMeta) {
+    this.policyMeta = policyMeta;
+    this.unparsed |= policyMeta.unparsed;
+    return this;
+  }
+
+  /**
+   * Metadata about the policy that triggered this status change.
+   *
+   * @return policyMeta
+   */
+  @jakarta.annotation.Nullable
+  @JsonProperty(JSON_PROPERTY_POLICY_META)
+  @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS)
+  public FlakyTestHistoryPolicyMeta getPolicyMeta() {
+    return policyMeta;
+  }
+
+  public void setPolicyMeta(FlakyTestHistoryPolicyMeta policyMeta) {
+    this.policyMeta = policyMeta;
+  }
+
   public FlakyTestHistory status(String status) {
     this.status = status;
     return this;
@@ -166,21 +221,25 @@ public boolean equals(Object o) {
     }
     FlakyTestHistory flakyTestHistory = (FlakyTestHistory) o;
     return Objects.equals(this.commitSha, flakyTestHistory.commitSha)
+        && Objects.equals(this.policyId, flakyTestHistory.policyId)
+        && Objects.equals(this.policyMeta, flakyTestHistory.policyMeta)
         && Objects.equals(this.status, flakyTestHistory.status)
         && Objects.equals(this.timestamp, flakyTestHistory.timestamp)
         && Objects.equals(this.additionalProperties, flakyTestHistory.additionalProperties);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(commitSha, status, timestamp, additionalProperties);
+    return Objects.hash(commitSha, policyId, policyMeta, status, timestamp, additionalProperties);
   }
 
   @Override
   public String toString() {
     StringBuilder sb = new StringBuilder();
     sb.append("class FlakyTestHistory {\n");
     sb.append("    commitSha: ").append(toIndentedString(commitSha)).append("\n");
+    sb.append("    policyId: ").append(toIndentedString(policyId)).append("\n");
+    sb.append("    policyMeta: ").append(toIndentedString(policyMeta)).append("\n");
     sb.append("    status: ").append(toIndentedString(status)).append("\n");
     sb.append("    timestamp: ").append(toIndentedString(timestamp)).append("\n");
     sb.append("    additionalProperties: ")