Clarify additionalProperties note is SDK-only; add per-language access patterns (#1716)

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

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

.generator/schemas/v1/openapi.yaml

@@ -22813,10 +22813,11 @@ components:
       description: |-
         Response with hourly report of all data billed by Datadog for all organizations.
 
-        Newly added billing dimensions and usage types appear as untyped keys on the
-        `additionalProperties` map instead of as typed fields. Call
-        `GET /api/v2/usage/summary/available_fields` to enumerate every key returned
-        at this response level—both typed fields and `additionalProperties` keys.
+        For SDK users only: all fields at this response level are accessible through the
+        `additionalProperties` map. Existing typed-field getters are unchanged. New billing
+        dimensions will not have typed-field getters. Use
+        [Get available fields for usage summary](https://docs.datadoghq.com/api/latest/usage-metering/#get-usage-summary-available-fields)
+        to enumerate every available key.
       properties:
         agent_host_top99p:
           description: Shows the 99th percentile of all agent hosts over all hours in the current date for all organizations.
@@ -24115,10 +24116,11 @@ components:
       description: |-
         Global hourly report of all data billed by Datadog for a given organization.
 
-        Newly added billing dimensions and usage types appear as untyped keys on the
-        `additionalProperties` map instead of as typed fields. Call
-        `GET /api/v2/usage/summary/available_fields` to enumerate every key returned
-        at this response level—both typed fields and `additionalProperties` keys.
+        For SDK users only: all fields at this response level are accessible through the
+        `additionalProperties` map. Existing typed-field getters are unchanged. New billing
+        dimensions will not have typed-field getters. Use
+        [Get available fields for usage summary](https://docs.datadoghq.com/api/latest/usage-metering/#get-usage-summary-available-fields)
+        to enumerate every available key.
       properties:
         account_name:
           description: The account name.
@@ -25436,10 +25438,11 @@ components:
         Response summarizing all usage aggregated across the months in the request for
         all organizations, and broken down by month and by organization.
 
-        Newly added billing dimensions and usage types appear as untyped keys on the
-        `additionalProperties` map instead of as typed fields. Call
-        `GET /api/v2/usage/summary/available_fields` to enumerate every key returned
-        at this response level—both typed fields and `additionalProperties` keys.
+        For SDK users only: all fields at this response level are accessible through the
+        `additionalProperties` map. Existing typed-field getters are unchanged. New billing
+        dimensions will not have typed-field getters. Use
+        [Get available fields for usage summary](https://docs.datadoghq.com/api/latest/usage-metering/#get-usage-summary-available-fields)
+        to enumerate every available key.
       properties:
         agent_host_top99p_sum:
           description: Shows the 99th percentile of all agent hosts over all hours in the current month for all organizations.
@@ -43215,11 +43218,12 @@ paths:
       description: |-
         Get all usage across your account.
 
-        Newly added billing dimensions and usage types appear as untyped keys on the
-        `additionalProperties` map of `UsageSummaryResponse`, `UsageSummaryDate`, and
-        `UsageSummaryDateOrg` instead of as typed fields. Call
-        `GET /api/v2/usage/summary/available_fields` to enumerate every key returned
-        at each response level—both typed fields and `additionalProperties` keys.
+        For SDK users only: all fields on `UsageSummaryResponse`, `UsageSummaryDate`, and
+        `UsageSummaryDateOrg` are accessible through each object's `additionalProperties` map.
+        Existing typed-field getters are unchanged. New billing dimensions will not have
+        typed-field getters. Use
+        [Get available fields for usage summary](https://docs.datadoghq.com/api/latest/usage-metering/#get-usage-summary-available-fields)
+        to enumerate every available key at each response level.
 
         This endpoint is only accessible for [parent-level organizations](https://docs.datadoghq.com/account_management/multi_organization/).
       operationId: GetUsageSummary

.generator/schemas/v2/openapi.yaml

@@ -187306,6 +187306,37 @@ paths:
         dimensions and usage types added after the v1 schema freeze).
 
         This endpoint is only accessible for [parent-level organizations](https://docs.datadoghq.com/account_management/multi_organization/).
+
+        Go example:
+
+        ```go
+        fields, _, err := api.GetUsageSummaryAvailableFields(ctx)
+        attr := fields.Data.GetAttributes()
+
+        // resp is the *UsageSummaryResponse returned by api.GetUsageSummary(ctx, ...)
+        // Layer 1: UsageSummaryResponse
+        for _, key := range attr.GetResponseFields() {
+            if val, ok := resp.AdditionalProperties[key]; ok {
+                fmt.Println(key, val.(json.Number))
+            }
+        }
+        // Layer 2: UsageSummaryDate (per month)
+        for _, date := range resp.GetUsage() {
+            for _, key := range attr.GetDateFields() {
+                if val, ok := date.AdditionalProperties[key]; ok {
+                    fmt.Println(key, val.(json.Number))
+                }
+            }
+            // Layer 3: UsageSummaryDateOrg (per org per month)
+            for _, org := range date.GetOrgs() {
+                for _, key := range attr.GetDateOrgFields() {
+                    if val, ok := org.AdditionalProperties[key]; ok {
+                        fmt.Println(key, val.(json.Number))
+                    }
+                }
+            }
+        }
+        ```
       operationId: GetUsageSummaryAvailableFields
       responses:
         "200":

src/datadogV1/api/api_usage_metering.rs

@@ -5284,11 +5284,12 @@ impl UsageMeteringAPI {
 
     /// Get all usage across your account.
     ///
-    /// Newly added billing dimensions and usage types appear as untyped keys on the
-    /// `additionalProperties` map of `UsageSummaryResponse`, `UsageSummaryDate`, and
-    /// `UsageSummaryDateOrg` instead of as typed fields. Call
-    /// `GET /api/v2/usage/summary/available_fields` to enumerate every key returned
-    /// at each response level—both typed fields and `additionalProperties` keys.
+    /// For SDK users only: all fields on `UsageSummaryResponse`, `UsageSummaryDate`, and
+    /// `UsageSummaryDateOrg` are accessible through each object's `additionalProperties` map.
+    /// Existing typed-field getters are unchanged. New billing dimensions will not have
+    /// typed-field getters. Use
+    /// [Get available fields for usage summary](<https://docs.datadoghq.com/api/latest/usage-metering/#get-usage-summary-available-fields>)
+    /// to enumerate every available key at each response level.
     ///
     /// This endpoint is only accessible for [parent-level organizations](<https://docs.datadoghq.com/account_management/multi_organization/>).
     pub async fn get_usage_summary(
@@ -5316,11 +5317,12 @@ impl UsageMeteringAPI {
 
     /// Get all usage across your account.
     ///
-    /// Newly added billing dimensions and usage types appear as untyped keys on the
-    /// `additionalProperties` map of `UsageSummaryResponse`, `UsageSummaryDate`, and
-    /// `UsageSummaryDateOrg` instead of as typed fields. Call
-    /// `GET /api/v2/usage/summary/available_fields` to enumerate every key returned
-    /// at each response level—both typed fields and `additionalProperties` keys.
+    /// For SDK users only: all fields on `UsageSummaryResponse`, `UsageSummaryDate`, and
+    /// `UsageSummaryDateOrg` are accessible through each object's `additionalProperties` map.
+    /// Existing typed-field getters are unchanged. New billing dimensions will not have
+    /// typed-field getters. Use
+    /// [Get available fields for usage summary](<https://docs.datadoghq.com/api/latest/usage-metering/#get-usage-summary-available-fields>)
+    /// to enumerate every available key at each response level.
     ///
     /// This endpoint is only accessible for [parent-level organizations](<https://docs.datadoghq.com/account_management/multi_organization/>).
     pub async fn get_usage_summary_with_http_info(

src/datadogV1/model/model_usage_summary_date.rs

@@ -8,10 +8,11 @@ use std::fmt::{self, Formatter};
 
 /// Response with hourly report of all data billed by Datadog for all organizations.
 ///
-/// Newly added billing dimensions and usage types appear as untyped keys on the
-/// `additionalProperties` map instead of as typed fields. Call
-/// `GET /api/v2/usage/summary/available_fields` to enumerate every key returned
-/// at this response level—both typed fields and `additionalProperties` keys.
+/// For SDK users only: all fields at this response level are accessible through the
+/// `additionalProperties` map. Existing typed-field getters are unchanged. New billing
+/// dimensions will not have typed-field getters. Use
+/// [Get available fields for usage summary](<https://docs.datadoghq.com/api/latest/usage-metering/#get-usage-summary-available-fields>)
+/// to enumerate every available key.
 #[non_exhaustive]
 #[skip_serializing_none]
 #[derive(Clone, Debug, PartialEq, Serialize)]

src/datadogV1/model/model_usage_summary_date_org.rs

@@ -8,10 +8,11 @@ use std::fmt::{self, Formatter};
 
 /// Global hourly report of all data billed by Datadog for a given organization.
 ///
-/// Newly added billing dimensions and usage types appear as untyped keys on the
-/// `additionalProperties` map instead of as typed fields. Call
-/// `GET /api/v2/usage/summary/available_fields` to enumerate every key returned
-/// at this response level—both typed fields and `additionalProperties` keys.
+/// For SDK users only: all fields at this response level are accessible through the
+/// `additionalProperties` map. Existing typed-field getters are unchanged. New billing
+/// dimensions will not have typed-field getters. Use
+/// [Get available fields for usage summary](<https://docs.datadoghq.com/api/latest/usage-metering/#get-usage-summary-available-fields>)
+/// to enumerate every available key.
 #[non_exhaustive]
 #[skip_serializing_none]
 #[derive(Clone, Debug, PartialEq, Serialize)]

src/datadogV1/model/model_usage_summary_response.rs

@@ -9,10 +9,11 @@ use std::fmt::{self, Formatter};
 /// Response summarizing all usage aggregated across the months in the request for
 /// all organizations, and broken down by month and by organization.
 ///
-/// Newly added billing dimensions and usage types appear as untyped keys on the
-/// `additionalProperties` map instead of as typed fields. Call
-/// `GET /api/v2/usage/summary/available_fields` to enumerate every key returned
-/// at this response level—both typed fields and `additionalProperties` keys.
+/// For SDK users only: all fields at this response level are accessible through the
+/// `additionalProperties` map. Existing typed-field getters are unchanged. New billing
+/// dimensions will not have typed-field getters. Use
+/// [Get available fields for usage summary](<https://docs.datadoghq.com/api/latest/usage-metering/#get-usage-summary-available-fields>)
+/// to enumerate every available key.
 #[non_exhaustive]
 #[skip_serializing_none]
 #[derive(Clone, Debug, PartialEq, Serialize)]

src/datadogV2/api/api_usage_metering.rs

@@ -2207,6 +2207,37 @@ impl UsageMeteringAPI {
     /// dimensions and usage types added after the v1 schema freeze).
     ///
     /// This endpoint is only accessible for [parent-level organizations](<https://docs.datadoghq.com/account_management/multi_organization/>).
+    ///
+    /// Go example:
+    ///
+    /// ```go
+    /// fields, _, err := api.GetUsageSummaryAvailableFields(ctx)
+    /// attr := fields.Data.GetAttributes()
+    ///
+    /// // resp is the *UsageSummaryResponse returned by api.GetUsageSummary(ctx, ...)
+    /// // Layer 1: UsageSummaryResponse
+    /// for _, key := range attr.GetResponseFields() {
+    ///     if val, ok := resp.AdditionalProperties[key]; ok {
+    ///         fmt.Println(key, val.(json.Number))
+    ///     }
+    /// }
+    /// // Layer 2: UsageSummaryDate (per month)
+    /// for _, date := range resp.GetUsage() {
+    ///     for _, key := range attr.GetDateFields() {
+    ///         if val, ok := date.AdditionalProperties[key]; ok {
+    ///             fmt.Println(key, val.(json.Number))
+    ///         }
+    ///     }
+    ///     // Layer 3: UsageSummaryDateOrg (per org per month)
+    ///     for _, org := range date.GetOrgs() {
+    ///         for _, key := range attr.GetDateOrgFields() {
+    ///             if val, ok := org.AdditionalProperties[key]; ok {
+    ///                 fmt.Println(key, val.(json.Number))
+    ///             }
+    ///         }
+    ///     }
+    /// }
+    /// ```
     pub async fn get_usage_summary_available_fields(
         &self,
     ) -> Result<
@@ -2237,6 +2268,37 @@ impl UsageMeteringAPI {
     /// dimensions and usage types added after the v1 schema freeze).
     ///
     /// This endpoint is only accessible for [parent-level organizations](<https://docs.datadoghq.com/account_management/multi_organization/>).
+    ///
+    /// Go example:
+    ///
+    /// ```go
+    /// fields, _, err := api.GetUsageSummaryAvailableFields(ctx)
+    /// attr := fields.Data.GetAttributes()
+    ///
+    /// // resp is the *UsageSummaryResponse returned by api.GetUsageSummary(ctx, ...)
+    /// // Layer 1: UsageSummaryResponse
+    /// for _, key := range attr.GetResponseFields() {
+    ///     if val, ok := resp.AdditionalProperties[key]; ok {
+    ///         fmt.Println(key, val.(json.Number))
+    ///     }
+    /// }
+    /// // Layer 2: UsageSummaryDate (per month)
+    /// for _, date := range resp.GetUsage() {
+    ///     for _, key := range attr.GetDateFields() {
+    ///         if val, ok := date.AdditionalProperties[key]; ok {
+    ///             fmt.Println(key, val.(json.Number))
+    ///         }
+    ///     }
+    ///     // Layer 3: UsageSummaryDateOrg (per org per month)
+    ///     for _, org := range date.GetOrgs() {
+    ///         for _, key := range attr.GetDateOrgFields() {
+    ///             if val, ok := org.AdditionalProperties[key]; ok {
+    ///                 fmt.Println(key, val.(json.Number))
+    ///             }
+    ///         }
+    ///     }
+    /// }
+    /// ```
     pub async fn get_usage_summary_available_fields_with_http_info(
         &self,
     ) -> Result<