Add deprecation warnings to API and models (#1111)

* Add deprecation warnings to API and models

* Fix oneOf doc

Author: therve

.generator/src/generator/templates/api.j2

@@ -31,6 +31,10 @@ module {{ module_name }}::{{ version|upper }}
     {{ operation.description|block_comment|indent(4) }}
     #
     {%- endif %}
+    {%- if operation.deprecated %}
+    # @deprecated This API is deprecated.
+    #
+    {%- endif %}
     {%- for name, parameter in operation|parameters if parameter.required %}
     # @param {{ name|attribute_name }} [{{ get_type_for_parameter(parameter) }}] {{ parameter.get("description", "").replace('\n', ' ') }}
     {%- endfor %}
@@ -40,6 +44,9 @@ module {{ module_name }}::{{ version|upper }}
     {%- endfor %}
     # @return [Array<({% if returnType %}{{ returnType }}{% else %}nil{% endif %}, Integer, Hash)>] {% if returnType %}{{ returnType }} data{% else %}nil{% endif %}, response status code and response headers
     def {{ operation.operationId|snake_case }}_with_http_info({% for name, parameter in operation|parameters if parameter.required %}{{ name|attribute_name }}, {% endfor %}opts = {})
+      {%- if operation.deprecated %}
+      warn "[DEPRECATION] `{{ operation.operationId }}` is deprecated."
+      {%- endif %}
       {%- if "x-unstable" in operation %}
       unstable_enabled = @api_client.config.unstable_operations["{{ version }}.{{ operation.operationId|snake_case }}".to_sym]
       if unstable_enabled

.generator/src/generator/templates/model.j2

@@ -7,6 +7,10 @@ require 'time'
 
 module {{ module_name }}::{{ version|upper }}
   # {{ model.description.rstrip()|replace('\n', '\n# ')|indent(2) }}
+{%- if model.deprecated %}
+  #
+  # @deprecated This model is deprecated.
+{%- endif %}
 {% if "enum" in model -%}
 {% include "model_enum.j2" %}
 {%- elif "oneOf" in model -%}

.generator/src/generator/templates/model_generic.j2

@@ -48,6 +48,9 @@
     # @param attributes [Hash] Model attributes in the form of hash
     # @!visibility private
     def initialize(attributes = {})
+      {%- if model.deprecated %}
+      warn "[DEPRECATION] `{{ name }}` is deprecated."
+      {%- endif %}
       if (!attributes.is_a?(Hash))
         fail ArgumentError, "The input argument (attributes) must be a hash in `{{ module_name }}::{{ version|upper }}::{{ name }}` initialize method"
       end

.generator/src/generator/templates/model_oneof.j2

@@ -39,7 +39,7 @@
       #}
       {%- endif %}
       # Builds the object
-      # @param [Mixed] Data to be matched against the list of oneOf items
+      # @param data [Mixed] Data to be matched against the list of oneOf items
       # @return [Object] Returns the model or the data itself
       def build(data)
       {%- if model.discriminator %}

lib/datadog_api_client/v1/api/logs_api.rb

@@ -128,12 +128,15 @@ def submit_log(body, opts = {})
     # - 413: Payload too large (batch is above 5MB uncompressed)
     # - 5xx: Internal error, request should be retried after some time
     #
+    # @deprecated This API is deprecated.
+    #
     # @param body [Array<HTTPLogItem>] Log to send (JSON format).
     # @param opts [Hash] the optional parameters
     # @option opts [ContentEncoding] :content_encoding HTTP header used to compress the media-type.
     # @option opts [String] :ddtags Log tags can be passed as query parameters with `text/plain` content type.
     # @return [Array<(Object, Integer, Hash)>] Object data, response status code and response headers
     def submit_log_with_http_info(body, opts = {})
+      warn "[DEPRECATION] `SubmitLog` is deprecated."
 
       if @api_client.config.debugging
         @api_client.config.logger.debug 'Calling API: LogsAPI.submit_log ...'

lib/datadog_api_client/v1/api/usage_metering_api.rb

@@ -37,13 +37,16 @@ def get_daily_custom_reports(opts = {})
     # **Note:** This endpoint will be fully deprecated on December 1, 2022.
     # Refer to [Migrating from v1 to v2 of the Usage Attribution API](https://docs.datadoghq.com/account_management/guide/usage-attribution-migration/) for the associated migration guide.
     #
+    # @deprecated This API is deprecated.
+    #
     # @param opts [Hash] the optional parameters
     # @option opts [Integer] :page_size The number of files to return in the response. `[default=60]`.
     # @option opts [Integer] :page_number The identifier of the first page to return. This parameter is used for the pagination feature `[default=0]`.
     # @option opts [UsageSortDirection] :sort_dir The direction to sort by: `[desc, asc]`.
     # @option opts [UsageSort] :sort The field to sort by: `[computed_on, size, start_date, end_date]`.
     # @return [Array<(UsageCustomReportsResponse, Integer, Hash)>] UsageCustomReportsResponse data, response status code and response headers
     def get_daily_custom_reports_with_http_info(opts = {})
+      warn "[DEPRECATION] `GetDailyCustomReports` is deprecated."
 
       if @api_client.config.debugging
         @api_client.config.logger.debug 'Calling API: UsageMeteringAPI.get_daily_custom_reports ...'
@@ -352,13 +355,16 @@ def get_monthly_custom_reports(opts = {})
     # **Note:** This endpoint will be fully deprecated on December 1, 2022.
     # Refer to [Migrating from v1 to v2 of the Usage Attribution API](https://docs.datadoghq.com/account_management/guide/usage-attribution-migration/) for the associated migration guide.
     #
+    # @deprecated This API is deprecated.
+    #
     # @param opts [Hash] the optional parameters
     # @option opts [Integer] :page_size The number of files to return in the response `[default=60].`
     # @option opts [Integer] :page_number The identifier of the first page to return. This parameter is used for the pagination feature `[default=0]`.
     # @option opts [UsageSortDirection] :sort_dir The direction to sort by: `[desc, asc]`.
     # @option opts [UsageSort] :sort The field to sort by: `[computed_on, size, start_date, end_date]`.
     # @return [Array<(UsageCustomReportsResponse, Integer, Hash)>] UsageCustomReportsResponse data, response status code and response headers
     def get_monthly_custom_reports_with_http_info(opts = {})
+      warn "[DEPRECATION] `GetMonthlyCustomReports` is deprecated."
 
       if @api_client.config.debugging
         @api_client.config.logger.debug 'Calling API: UsageMeteringAPI.get_monthly_custom_reports ...'
@@ -541,10 +547,13 @@ def get_specified_daily_custom_reports(report_id, opts = {})
     # **Note:** This endpoint will be fully deprecated on December 1, 2022.
     # Refer to [Migrating from v1 to v2 of the Usage Attribution API](https://docs.datadoghq.com/account_management/guide/usage-attribution-migration/) for the associated migration guide.
     #
+    # @deprecated This API is deprecated.
+    #
     # @param report_id [String] Date of the report in the format `YYYY-MM-DD`.
     # @param opts [Hash] the optional parameters
     # @return [Array<(UsageSpecifiedCustomReportsResponse, Integer, Hash)>] UsageSpecifiedCustomReportsResponse data, response status code and response headers
     def get_specified_daily_custom_reports_with_http_info(report_id, opts = {})
+      warn "[DEPRECATION] `GetSpecifiedDailyCustomReports` is deprecated."
 
       if @api_client.config.debugging
         @api_client.config.logger.debug 'Calling API: UsageMeteringAPI.get_specified_daily_custom_reports ...'
@@ -608,10 +617,13 @@ def get_specified_monthly_custom_reports(report_id, opts = {})
     # **Note:** This endpoint will be fully deprecated on December 1, 2022.
     # Refer to [Migrating from v1 to v2 of the Usage Attribution API](https://docs.datadoghq.com/account_management/guide/usage-attribution-migration/) for the associated migration guide.
     #
+    # @deprecated This API is deprecated.
+    #
     # @param report_id [String] Date of the report in the format `YYYY-MM-DD`.
     # @param opts [Hash] the optional parameters
     # @return [Array<(UsageSpecifiedCustomReportsResponse, Integer, Hash)>] UsageSpecifiedCustomReportsResponse data, response status code and response headers
     def get_specified_monthly_custom_reports_with_http_info(report_id, opts = {})
+      warn "[DEPRECATION] `GetSpecifiedMonthlyCustomReports` is deprecated."
 
       if @api_client.config.debugging
         @api_client.config.logger.debug 'Calling API: UsageMeteringAPI.get_specified_monthly_custom_reports ...'
@@ -744,6 +756,8 @@ def get_usage_attribution(start_month, fields, opts = {})
     # **Note:** This endpoint will be fully deprecated on December 1, 2022.
     # Refer to [Migrating from v1 to v2 of the Usage Attribution API](https://docs.datadoghq.com/account_management/guide/usage-attribution-migration/) for the associated migration guide.
     #
+    # @deprecated This API is deprecated.
+    #
     # @param start_month [Time] Datetime in ISO-8601 format, UTC, precise to month: `[YYYY-MM]` for usage beginning in this month. Maximum of 15 months ago.
     # @param fields [UsageAttributionSupportedMetrics] Comma-separated list of usage types to return, or `*` for all usage types.
     # @param opts [Hash] the optional parameters
@@ -755,6 +769,7 @@ def get_usage_attribution(start_month, fields, opts = {})
     # @option opts [Integer] :limit Maximum number of records to be returned.
     # @return [Array<(UsageAttributionResponse, Integer, Hash)>] UsageAttributionResponse data, response status code and response headers
     def get_usage_attribution_with_http_info(start_month, fields, opts = {})
+      warn "[DEPRECATION] `GetUsageAttribution` is deprecated."
 
       if @api_client.config.debugging
         @api_client.config.logger.debug 'Calling API: UsageMeteringAPI.get_usage_attribution ...'
@@ -2426,11 +2441,14 @@ def get_usage_synthetics(start_hr, opts = {})
     # Get hourly usage for [synthetics checks](https://docs.datadoghq.com/synthetics/).
     # **Note:** hourly usage data for all products is now available in the [Get hourly usage by product family API](https://docs.datadoghq.com/api/latest/usage-metering/#get-hourly-usage-by-product-family). Refer to [Migrating from the V1 Hourly Usage APIs to V2](https://docs.datadoghq.com/account_management/guide/hourly-usage-migration/) for the associated migration guide.
     #
+    # @deprecated This API is deprecated.
+    #
     # @param start_hr [Time] Datetime in ISO-8601 format, UTC, precise to hour: [YYYY-MM-DDThh] for usage beginning at this hour.
     # @param opts [Hash] the optional parameters
     # @option opts [Time] :end_hr Datetime in ISO-8601 format, UTC, precise to hour: [YYYY-MM-DDThh] for usage ending **before** this hour.
     # @return [Array<(UsageSyntheticsResponse, Integer, Hash)>] UsageSyntheticsResponse data, response status code and response headers
     def get_usage_synthetics_with_http_info(start_hr, opts = {})
+      warn "[DEPRECATION] `GetUsageSynthetics` is deprecated."
 
       if @api_client.config.debugging
         @api_client.config.logger.debug 'Calling API: UsageMeteringAPI.get_usage_synthetics ...'

lib/datadog_api_client/v1/models/distribution_point_item.rb

@@ -31,7 +31,7 @@ def openapi_one_of
         ]
       end
       # Builds the object
-      # @param [Mixed] Data to be matched against the list of oneOf items
+      # @param data [Mixed] Data to be matched against the list of oneOf items
       # @return [Object] Returns the model or the data itself
       def build(data)
         # Go through the list of oneOf items and attempt to identify the appropriate one.

lib/datadog_api_client/v1/models/distribution_widget_histogram_request_query.rb

@@ -32,7 +32,7 @@ def openapi_one_of
         ]
       end
       # Builds the object
-      # @param [Mixed] Data to be matched against the list of oneOf items
+      # @param data [Mixed] Data to be matched against the list of oneOf items
       # @return [Object] Returns the model or the data itself
       def build(data)
         # Go through the list of oneOf items and attempt to identify the appropriate one.

lib/datadog_api_client/v1/models/formula_and_function_query_definition.rb

@@ -34,7 +34,7 @@ def openapi_one_of
         ]
       end
       # Builds the object
-      # @param [Mixed] Data to be matched against the list of oneOf items
+      # @param data [Mixed] Data to be matched against the list of oneOf items
       # @return [Object] Returns the model or the data itself
       def build(data)
         # Go through the list of oneOf items and attempt to identify the appropriate one.

lib/datadog_api_client/v1/models/logs_processor.rb

@@ -44,7 +44,7 @@ def openapi_one_of
         ]
       end
       # Builds the object
-      # @param [Mixed] Data to be matched against the list of oneOf items
+      # @param data [Mixed] Data to be matched against the list of oneOf items
       # @return [Object] Returns the model or the data itself
       def build(data)
         # Go through the list of oneOf items and attempt to identify the appropriate one.