Clarify metrics API query strings (#1537)

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

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

.generator/schemas/v2/openapi.yaml

@@ -107944,6 +107944,8 @@ paths:
     get:
       description: |-
         Get a list of actively reporting metrics for your organization. Pagination is optional using the `page[cursor]` and `page[size]` query parameters.
+
+        Query parameters use bracket notation (for example, `filter[tags]`, `filter[queried][window][seconds]`). Pass them as standard URL query strings, URL-encoding the brackets if your client does not handle them. For example: `GET /api/v2/metrics?filter[tags]=env:prod&window[seconds]=86400&page[size]=500`.
       operationId: ListTagConfigurations
       parameters:
         - description: Only return custom metrics that have been configured with Metrics Without Limits.
@@ -107983,7 +107985,7 @@ paths:
           schema:
             type: boolean
         - description: |-
-            Only return metrics that have been queried or not queried in the specified window. Dependent on being sent with `filter[queried]`. The default value is 2,592,000 seconds (30 days), the maximum value is 15,552,000 seconds (180 days), and the minimum value is 1 second.
+            This parameter has no effect unless `filter[queried]` is also set. Only return metrics that have been queried or not queried in the specified window. The default value is 2,592,000 seconds (30 days), the maximum value is 15,552,000 seconds (180 days), and the minimum value is 1 second. For example: `filter[queried]=true&filter[queried][window][seconds]=604800`.
           example: 15552000
           in: query
           name: filter[queried][window][seconds]
@@ -107995,7 +107997,7 @@ paths:
             minimum: 1
             type: integer
         - description: |-
-            Only return metrics that were submitted with tags matching this expression. You can use AND, OR, IN, and wildcards (for example, service:web*).
+            Only return metrics that were submitted with tags matching this expression. You can use AND, OR, IN, and wildcards. For example: `filter[tags]=env IN (staging,test) AND service:web*`.
           example: "env IN (staging,test) AND service:web*"
           in: query
           name: filter[tags]
@@ -108022,7 +108024,8 @@ paths:
             maximum: 2592000
             minimum: 1
             type: integer
-        - description: Maximum number of results per page. Use with `page[cursor]` for pagination. The default value is 10000, the maximum value is 10000, and the minimum value is 1.
+        - description: |-
+            Maximum number of results per page. Send `page[size]` on the first request to opt in to pagination. On each subsequent request, send `page[cursor]` set to the value of `meta.pagination.next_cursor` from the previous response. The default value is 10000, the maximum value is 10000, and the minimum value is 1.
           in: query
           name: page[size]
           required: false
@@ -108426,7 +108429,8 @@ paths:
       operationId: EstimateMetricsOutputSeries
       parameters:
         - $ref: "#/components/parameters/MetricName"
-        - description: Filtered tag keys that the metric is configured to query with.
+        - description: |-
+            Comma-separated list of tag keys that the metric is configured to query with. For example: `filter[groups]=app,host`.
           example: "app,host"
           in: query
           name: filter[groups]

src/datadogV2/api/api_metrics.rs

@@ -16,7 +16,7 @@ use std::io::Write;
 #[non_exhaustive]
 #[derive(Clone, Default, Debug)]
 pub struct EstimateMetricsOutputSeriesOptionalParams {
-    /// Filtered tag keys that the metric is configured to query with.
+    /// Comma-separated list of tag keys that the metric is configured to query with. For example: `filter[groups]=app,host`.
     pub filter_groups: Option<String>,
     /// The number of hours of look back (from now) to estimate cardinality with. If unspecified, it defaults to 0 hours.
     pub filter_hours_ago: Option<i32>,
@@ -29,7 +29,7 @@ pub struct EstimateMetricsOutputSeriesOptionalParams {
 }
 
 impl EstimateMetricsOutputSeriesOptionalParams {
-    /// Filtered tag keys that the metric is configured to query with.
+    /// Comma-separated list of tag keys that the metric is configured to query with. For example: `filter[groups]=app,host`.
     pub fn filter_groups(mut self, value: String) -> Self {
         self.filter_groups = Some(value);
         self
@@ -89,15 +89,15 @@ pub struct ListTagConfigurationsOptionalParams {
     pub filter_include_percentiles: Option<bool>,
     /// Only return metrics that have been queried (true) or not queried (false) in the look back window. Set the window with `filter[queried][window][seconds]`; if omitted, a default window is used.
     pub filter_queried: Option<bool>,
-    /// Only return metrics that have been queried or not queried in the specified window. Dependent on being sent with `filter[queried]`. The default value is 2,592,000 seconds (30 days), the maximum value is 15,552,000 seconds (180 days), and the minimum value is 1 second.
+    /// This parameter has no effect unless `filter[queried]` is also set. Only return metrics that have been queried or not queried in the specified window. The default value is 2,592,000 seconds (30 days), the maximum value is 15,552,000 seconds (180 days), and the minimum value is 1 second. For example: `filter[queried]=true&filter[queried][window][seconds]=604800`.
     pub filter_queried_window_seconds: Option<i64>,
-    /// Only return metrics that were submitted with tags matching this expression. You can use AND, OR, IN, and wildcards (for example, service:web*).
+    /// Only return metrics that were submitted with tags matching this expression. You can use AND, OR, IN, and wildcards. For example: `filter[tags]=env IN (staging,test) AND service:web*`.
     pub filter_tags: Option<String>,
     /// Only return metrics that are used in at least one dashboard, monitor, notebook, or SLO.
     pub filter_related_assets: Option<bool>,
     /// Only return metrics that have been actively reporting in the specified window. The default value is 3600 seconds (1 hour), the maximum value is 2,592,000 seconds (30 days), and the minimum value is 1 second.
     pub window_seconds: Option<i64>,
-    /// Maximum number of results per page. Use with `page[cursor]` for pagination. The default value is 10000, the maximum value is 10000, and the minimum value is 1.
+    /// Maximum number of results per page. Send `page[size]` on the first request to opt in to pagination. On each subsequent request, send `page[cursor]` set to the value of `meta.pagination.next_cursor` from the previous response. The default value is 10000, the maximum value is 10000, and the minimum value is 1.
     pub page_size: Option<i32>,
     /// Cursor for pagination. Use `page[size]` to opt-in to pagination and get the first page; for subsequent pages, use the value from `meta.pagination.next_cursor` in the response. Pagination is complete when `next_cursor` is null.
     pub page_cursor: Option<String>,
@@ -132,12 +132,12 @@ impl ListTagConfigurationsOptionalParams {
         self.filter_queried = Some(value);
         self
     }
-    /// Only return metrics that have been queried or not queried in the specified window. Dependent on being sent with `filter[queried]`. The default value is 2,592,000 seconds (30 days), the maximum value is 15,552,000 seconds (180 days), and the minimum value is 1 second.
+    /// This parameter has no effect unless `filter[queried]` is also set. Only return metrics that have been queried or not queried in the specified window. The default value is 2,592,000 seconds (30 days), the maximum value is 15,552,000 seconds (180 days), and the minimum value is 1 second. For example: `filter[queried]=true&filter[queried][window][seconds]=604800`.
     pub fn filter_queried_window_seconds(mut self, value: i64) -> Self {
         self.filter_queried_window_seconds = Some(value);
         self
     }
-    /// Only return metrics that were submitted with tags matching this expression. You can use AND, OR, IN, and wildcards (for example, service:web*).
+    /// Only return metrics that were submitted with tags matching this expression. You can use AND, OR, IN, and wildcards. For example: `filter[tags]=env IN (staging,test) AND service:web*`.
     pub fn filter_tags(mut self, value: String) -> Self {
         self.filter_tags = Some(value);
         self
@@ -152,7 +152,7 @@ impl ListTagConfigurationsOptionalParams {
         self.window_seconds = Some(value);
         self
     }
-    /// Maximum number of results per page. Use with `page[cursor]` for pagination. The default value is 10000, the maximum value is 10000, and the minimum value is 1.
+    /// Maximum number of results per page. Send `page[size]` on the first request to opt in to pagination. On each subsequent request, send `page[cursor]` set to the value of `meta.pagination.next_cursor` from the previous response. The default value is 10000, the maximum value is 10000, and the minimum value is 1.
     pub fn page_size(mut self, value: i32) -> Self {
         self.page_size = Some(value);
         self
@@ -1657,6 +1657,8 @@ impl MetricsAPI {
     }
 
     /// Get a list of actively reporting metrics for your organization. Pagination is optional using the `page[cursor]` and `page[size]` query parameters.
+    ///
+    /// Query parameters use bracket notation (for example, `filter[tags]`, `filter[queried][window][seconds]`). Pass them as standard URL query strings, URL-encoding the brackets if your client does not handle them. For example: `GET /api/v2/metrics?filter[tags]=env:prod&window[seconds]=86400&page[size]=500`.
     pub async fn list_tag_configurations(
         &self,
         params: ListTagConfigurationsOptionalParams,
@@ -1717,6 +1719,8 @@ impl MetricsAPI {
     }
 
     /// Get a list of actively reporting metrics for your organization. Pagination is optional using the `page[cursor]` and `page[size]` query parameters.
+    ///
+    /// Query parameters use bracket notation (for example, `filter[tags]`, `filter[queried][window][seconds]`). Pass them as standard URL query strings, URL-encoding the brackets if your client does not handle them. For example: `GET /api/v2/metrics?filter[tags]=env:prod&window[seconds]=86400&page[size]=500`.
     pub async fn list_tag_configurations_with_http_info(
         &self,
         params: ListTagConfigurationsOptionalParams,