[REDHOSTS-612] Update Tags API Documentation (#2998)

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

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

.generator/schemas/v1/openapi.yaml

@@ -4219,14 +4219,14 @@ components:
           type: boolean
       type: object
     HostTags:
-      description: Set of tags to associate with your host.
+      description: Host name and an array of its tags
       properties:
         host:
           description: Your host name.
           example: test.host
           type: string
         tags:
-          description: A list of tags to apply to the host.
+          description: A list of tags associated with a host.
           items:
             description: A given tag in a list.
             example: environment:production
@@ -18972,18 +18972,18 @@ components:
       - match
       type: object
     TagToHosts:
-      description: In this object, the key is the tag, the value is a list of host
-        names that are reporting that tag.
+      description: In this object, the key is the tag, and the value is a list of
+        host names that are reporting that tag.
       properties:
         tags:
           additionalProperties:
-            description: A list of additional properties for tags.
+            description: A list of host names which contain this tag
             items:
               description: A given tag in a list.
               example: test.metric.host
               type: string
             type: array
-          description: A list of tags to apply to the host.
+          description: A mapping of tags to host names
           type: object
       type: object
     TargetFormatType:
@@ -36008,11 +36008,13 @@ paths:
         - synthetics_global_variable_write
   /api/v1/tags/hosts:
     get:
-      description: Return a mapping of tags to hosts for your whole infrastructure.
+      description: Returns a mapping of tags to hosts. For each tag, the response
+        returns a list of host names that contain this tag. There is a restriction
+        of 10k total host names from the org that can be attached to tags and returned.
       operationId: ListHostTags
       parameters:
-      - description: When specified, filters host list to those tags with the specified
-          source.
+      - description: Source to filter. [Complete list of source attribute values](https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value).
+          Use "user" source for custom-defined tags.
         in: query
         name: source
         required: false
@@ -36043,29 +36045,29 @@ paths:
       - apiKeyAuth: []
         appKeyAuth: []
       - AuthZ: []
-      summary: Get Tags
+      summary: Get All Host Tags
       tags:
       - Tags
       x-permission:
         operator: OPEN
         permissions: []
   /api/v1/tags/hosts/{host_name}:
     delete:
-      description: 'This endpoint allows you to remove all user-assigned tags
+      description: 'This endpoint allows you to remove all tags
 
-        for a single host.'
+        for a single host. If no source is specified, only deletes from the source
+        "User".'
       operationId: DeleteHostTags
       parameters:
-      - description: This endpoint allows you to remove all user-assigned tags for
-          a single host.
+      - description: Specified host name to delete tags
         in: path
         name: host_name
         required: true
         schema:
           type: string
-      - description: 'The source of the tags (for example chef, puppet).
-
-          [Complete list of source attribute values](https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value).'
+      - description: Source of the tags to be deleted. [Complete list of source attribute
+          values](https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value).
+          Use "user" source for custom-defined tags.
         in: query
         name: source
         required: false
@@ -36095,14 +36097,14 @@ paths:
       description: Return the list of tags that apply to a given host.
       operationId: GetHostTags
       parameters:
-      - description: When specified, filters list of tags to those tags with the specified
-          source.
+      - description: Name of the host to retrieve tags for
         in: path
         name: host_name
         required: true
         schema:
           type: string
-      - description: Source to filter.
+      - description: Source to filter. [Complete list of source attribute values](https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value).
+          Use "user" source for custom-defined tags.
         in: query
         name: source
         required: false
@@ -36129,25 +36131,25 @@ paths:
           description: Not Found
         '429':
           $ref: '#/components/responses/TooManyRequestsResponse'
-      summary: Get host tags
+      summary: Get Host Tags
       tags:
       - Tags
     post:
       description: 'This endpoint allows you to add new tags to a host,
 
-        optionally specifying where these tags come from.'
+        optionally specifying what source these tags come from. If tags already exist,
+        appends new tags to the tag list. If no source is specified, defaults to "user".'
       operationId: CreateHostTags
       parameters:
-      - description: This endpoint allows you to add new tags to a host, optionally
-          specifying where the tags came from.
+      - description: Specified host name to add new tags
         in: path
         name: host_name
         required: true
         schema:
           type: string
-      - description: 'The source of the tags.
-
-          [Complete list of source attribute values](https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value).'
+      - description: Source to add tags. [Complete list of source attribute values](https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value).
+          Use "user" source for custom-defined tags. If no source is specified, defaults
+          to "user".
         example: chef
         in: query
         name: source
@@ -36192,16 +36194,15 @@ paths:
         an integration source with those supplied in the request.'
       operationId: UpdateHostTags
       parameters:
-      - description: This endpoint allows you to update/replace all in an integration
-          source with those supplied in the request.
+      - description: Specified host name to change tags
         in: path
         name: host_name
         required: true
         schema:
           type: string
-      - description: 'The source of the tags (for example chef, puppet).
-
-          [Complete list of source attribute values](https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value)'
+      - description: Source to update tags. [Complete list of source attribute values](https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value).
+          Use "user" source for custom-defined tags. If no source specified, defaults
+          to "user".
         in: query
         name: source
         required: false
@@ -39217,7 +39218,8 @@ tags:
 
     by a source. For example, some valid sources include nagios, hudson, jenkins,
 
-    users, feed, chef, puppet, git, bitbucket, fabric, capistrano, etc.
+    users, feed, chef, puppet, git, bitbucket, fabric, capistrano, etc. Find a complete
+    list of source type names under [API Source Attributes](https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value).
 
 
     Read more about tags on [Getting Started with Tags](https://docs.datadoghq.com/getting_started/tagging/).'

examples/v1/tags/GetHostTags.py

@@ -1,5 +1,5 @@
 """
-Get host tags returns "OK" response
+Get Host Tags returns "OK" response
 """
 
 from datadog_api_client import ApiClient, Configuration

examples/v1/tags/ListHostTags.py

@@ -1,5 +1,5 @@
 """
-Get Tags returns "OK" response
+Get All Host Tags returns "OK" response
 """
 
 from datadog_api_client import ApiClient, Configuration

src/datadog_api_client/v1/api/tags_api.py

@@ -25,7 +25,7 @@ class TagsApi:
 
     The component of your infrastructure responsible for a tag is identified
     by a source. For example, some valid sources include nagios, hudson, jenkins,
-    users, feed, chef, puppet, git, bitbucket, fabric, capistrano, etc.
+    users, feed, chef, puppet, git, bitbucket, fabric, capistrano, etc. Find a complete list of source type names under `API Source Attributes <https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value>`_.
 
     Read more about tags on `Getting Started with Tags <https://docs.datadoghq.com/getting_started/tagging/>`_.
     """
@@ -185,14 +185,13 @@ def create_host_tags(
         """Add tags to a host.
 
         This endpoint allows you to add new tags to a host,
-        optionally specifying where these tags come from.
+        optionally specifying what source these tags come from. If tags already exist, appends new tags to the tag list. If no source is specified, defaults to "user".
 
-        :param host_name: This endpoint allows you to add new tags to a host, optionally specifying where the tags came from.
+        :param host_name: Specified host name to add new tags
         :type host_name: str
         :param body: Update host tags request body.
         :type body: HostTags
-        :param source: The source of the tags.
-            `Complete list of source attribute values <https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value>`_.
+        :param source: Source to add tags. `Complete list of source attribute values <https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value>`_. Use "user" source for custom-defined tags. If no source is specified, defaults to "user".
         :type source: str, optional
         :rtype: HostTags
         """
@@ -214,13 +213,12 @@ def delete_host_tags(
     ) -> None:
         """Remove host tags.
 
-        This endpoint allows you to remove all user-assigned tags
-        for a single host.
+        This endpoint allows you to remove all tags
+        for a single host. If no source is specified, only deletes from the source "User".
 
-        :param host_name: This endpoint allows you to remove all user-assigned tags for a single host.
+        :param host_name: Specified host name to delete tags
         :type host_name: str
-        :param source: The source of the tags (for example chef, puppet).
-            `Complete list of source attribute values <https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value>`_.
+        :param source: Source of the tags to be deleted. `Complete list of source attribute values <https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value>`_. Use "user" source for custom-defined tags.
         :type source: str, optional
         :rtype: None
         """
@@ -238,13 +236,13 @@ def get_host_tags(
         *,
         source: Union[str, UnsetType] = unset,
     ) -> HostTags:
-        """Get host tags.
+        """Get Host Tags.
 
         Return the list of tags that apply to a given host.
 
-        :param host_name: When specified, filters list of tags to those tags with the specified source.
+        :param host_name: Name of the host to retrieve tags for
         :type host_name: str
-        :param source: Source to filter.
+        :param source: Source to filter. `Complete list of source attribute values <https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value>`_. Use "user" source for custom-defined tags.
         :type source: str, optional
         :rtype: HostTags
         """
@@ -261,11 +259,11 @@ def list_host_tags(
         *,
         source: Union[str, UnsetType] = unset,
     ) -> TagToHosts:
-        """Get Tags.
+        """Get All Host Tags.
 
-        Return a mapping of tags to hosts for your whole infrastructure.
+        Returns a mapping of tags to hosts. For each tag, the response returns a list of host names that contain this tag. There is a restriction of 10k total host names from the org that can be attached to tags and returned.
 
-        :param source: When specified, filters host list to those tags with the specified source.
+        :param source: Source to filter. `Complete list of source attribute values <https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value>`_. Use "user" source for custom-defined tags.
         :type source: str, optional
         :rtype: TagToHosts
         """
@@ -287,12 +285,11 @@ def update_host_tags(
         This endpoint allows you to update/replace all tags in
         an integration source with those supplied in the request.
 
-        :param host_name: This endpoint allows you to update/replace all in an integration source with those supplied in the request.
+        :param host_name: Specified host name to change tags
         :type host_name: str
         :param body: Add tags to host
         :type body: HostTags
-        :param source: The source of the tags (for example chef, puppet).
-            `Complete list of source attribute values <https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value>`_
+        :param source: Source to update tags. `Complete list of source attribute values <https://docs.datadoghq.com/integrations/faq/list-of-api-source-attribute-value>`_. Use "user" source for custom-defined tags. If no source specified, defaults to "user".
         :type source: str, optional
         :rtype: HostTags
         """

src/datadog_api_client/v1/model/host_tags.py

@@ -28,12 +28,12 @@ def openapi_types(_):
 
     def __init__(self_, host: Union[str, UnsetType] = unset, tags: Union[List[str], UnsetType] = unset, **kwargs):
         """
-        Set of tags to associate with your host.
+        Host name and an array of its tags
 
         :param host: Your host name.
         :type host: str, optional
 
-        :param tags: A list of tags to apply to the host.
+        :param tags: A list of tags associated with a host.
         :type tags: [str], optional
         """
         if host is not unset:

src/datadog_api_client/v1/model/tag_to_hosts.py

@@ -26,9 +26,9 @@ def openapi_types(_):
 
     def __init__(self_, tags: Union[Dict[str, List[str]], UnsetType] = unset, **kwargs):
         """
-        In this object, the key is the tag, the value is a list of host names that are reporting that tag.
+        In this object, the key is the tag, and the value is a list of host names that are reporting that tag.
 
-        :param tags: A list of tags to apply to the host.
+        :param tags: A mapping of tags to host names
         :type tags: {str: ([str],)}, optional
         """
         if tags is not unset:

tests/v1/features/tags.feature

@@ -6,8 +6,11 @@ Feature: Tags
   tags to a particular host.  The component of your infrastructure
   responsible for a tag is identified by a source. For example, some valid
   sources include nagios, hudson, jenkins, users, feed, chef, puppet, git,
-  bitbucket, fabric, capistrano, etc.  Read more about tags on [Getting
-  Started with Tags](https://docs.datadoghq.com/getting_started/tagging/).
+  bitbucket, fabric, capistrano, etc. Find a complete list of source type
+  names under [API Source
+  Attributes](https://docs.datadoghq.com/integrations/faq/list-of-api-
+  source-attribute-value).  Read more about tags on [Getting Started with
+  Tags](https://docs.datadoghq.com/getting_started/tagging/).
 
   Background:
     Given a valid "apiKeyAuth" key in the system
@@ -31,26 +34,26 @@ Feature: Tags
     Then the response status is 404 Not Found
 
   @generated @skip @team:DataDog/core-index
-  Scenario: Get Tags returns "Not Found" response
+  Scenario: Get All Host Tags returns "Not Found" response
     Given new "ListHostTags" request
     When the request is sent
     Then the response status is 404 Not Found
 
   @generated @skip @team:DataDog/core-index
-  Scenario: Get Tags returns "OK" response
+  Scenario: Get All Host Tags returns "OK" response
     Given new "ListHostTags" request
     When the request is sent
     Then the response status is 200 OK
 
   @generated @skip @team:DataDog/core-index
-  Scenario: Get host tags returns "Not Found" response
+  Scenario: Get Host Tags returns "Not Found" response
     Given new "GetHostTags" request
     And request contains "host_name" parameter from "REPLACE.ME"
     When the request is sent
     Then the response status is 404 Not Found
 
   @generated @skip @team:DataDog/core-index
-  Scenario: Get host tags returns "OK" response
+  Scenario: Get Host Tags returns "OK" response
     Given new "GetHostTags" request
     And request contains "host_name" parameter from "REPLACE.ME"
     When the request is sent