Update api/v2/incidents/id/attachment endpoints documentation (#3059)

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

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

.generator/schemas/v2/openapi.yaml

@@ -178,6 +178,14 @@ components:
       required: true
       schema:
         type: string
+    AttachmentIDPathParameter:
+      description: The ID of the attachment.
+      in: path
+      name: attachment_id
+      required: true
+      schema:
+        example: 00000000-0000-0000-0000-000000000001
+        type: string
     AttachmentIncludeQueryParameter:
       description: 'Resource to include in the response. Supported value: `last_modified_by_user`.'
       explode: false
@@ -5340,6 +5348,8 @@ components:
       - project
       type: object
     Attachment:
+      description: An attachment response containing the attachment data and related
+        objects.
       properties:
         data:
           $ref: '#/components/schemas/AttachmentData'
@@ -5349,22 +5359,9 @@ components:
           type: array
       type: object
     AttachmentArray:
+      description: A list of incident attachments.
       properties:
         data:
-          example:
-          - attributes:
-              attachment:
-                documentUrl: https://app.datadoghq.com/notebook/123/Postmortem-IR-123
-                title: Postmortem IR-123
-              attachment_type: postmortem
-              modified: '2025-01-01T01:01:01.000000001Z'
-            id: 00000000-abcd-0002-0000-000000000000
-            relationships:
-              last_modified_by_user:
-                data:
-                  id: 00000000-0000-0000-cccc-000000000000
-                  type: users
-            type: incident_attachments
           items:
             $ref: '#/components/schemas/AttachmentData'
           type: array
@@ -5376,24 +5373,12 @@ components:
       - data
       type: object
     AttachmentData:
-      example:
-        attributes:
-          attachment:
-            documentUrl: https://app.datadoghq.com/notebook/123/Postmortem-IR-123
-            title: Postmortem IR-123
-          attachment_type: postmortem
-          modified: '2025-01-01T01:01:01.000000001Z'
-        id: 00000000-abcd-0002-0000-000000000000
-        relationships:
-          last_modified_by_user:
-            data:
-              id: 00000000-0000-0000-cccc-000000000000
-              type: users
-        type: incident_attachments
+      description: Attachment data from a response.
       properties:
         attributes:
           $ref: '#/components/schemas/AttachmentDataAttributes'
         id:
+          description: The unique identifier of the attachment.
           example: 00000000-abcd-0002-0000-000000000000
           type: string
         relationships:
@@ -5407,56 +5392,52 @@ components:
       - id
       type: object
     AttachmentDataAttributes:
+      description: The attachment's attributes.
       properties:
         attachment:
           $ref: '#/components/schemas/AttachmentDataAttributesAttachment'
         attachment_type:
           $ref: '#/components/schemas/AttachmentDataAttributesAttachmentType'
         modified:
+          description: Timestamp when the attachment was last modified.
+          example: '2025-01-01T01:01:01.000000001Z'
           format: date-time
           type: string
       type: object
     AttachmentDataAttributesAttachment:
+      description: The attachment object.
       properties:
         documentUrl:
+          description: The URL of the attachment.
+          example: https://app.datadoghq.com/notebook/123/Postmortem-IR-123
           type: string
         title:
+          description: The title of the attachment.
+          example: Postmortem IR-123
           type: string
       type: object
     AttachmentDataAttributesAttachmentType:
+      description: The type of the attachment.
       enum:
       - postmortem
       - link
+      example: postmortem
       type: string
       x-enum-varnames:
       - POSTMORTEM
       - LINK
     AttachmentDataRelationships:
+      description: The attachment's resource relationships.
       properties:
+        incident:
+          $ref: '#/components/schemas/RelationshipToIncident'
         last_modified_by_user:
-          $ref: '#/components/schemas/AttachmentDataRelationshipsLastModifiedByUser'
-      type: object
-    AttachmentDataRelationshipsLastModifiedByUser:
-      properties:
-        data:
-          $ref: '#/components/schemas/AttachmentDataRelationshipsLastModifiedByUserData'
-      required:
-      - data
-      type: object
-    AttachmentDataRelationshipsLastModifiedByUserData:
-      properties:
-        id:
-          example: ''
-          type: string
-        type:
-          $ref: '#/components/schemas/UserType'
-      required:
-      - type
-      - id
+          $ref: '#/components/schemas/RelationshipToUser'
       type: object
     AttachmentIncluded:
+      description: Objects related to an attachment.
       oneOf:
-      - $ref: '#/components/schemas/User140420082644000'
+      - $ref: '#/components/schemas/IncidentUserData'
     AuditLogsEvent:
       description: Object description of an Audit Logs event after it is processed
         and stored by Datadog.
@@ -13143,20 +13124,13 @@ components:
       - type
       type: object
     CreateAttachmentRequest:
-      example:
-        data:
-          attributes:
-            attachment:
-              documentUrl: https://app.datadoghq.com/notebook/123/Postmortem-IR-123
-              title: Postmortem-IR-123
-            attachment_type: postmortem
-          id: 00000000-0000-0000-0000-000000000000
-          type: incident_attachments
+      description: Create request for an attachment.
       properties:
         data:
           $ref: '#/components/schemas/CreateAttachmentRequestData'
       type: object
     CreateAttachmentRequestData:
+      description: Attachment data for a create request.
       properties:
         attributes:
           $ref: '#/components/schemas/CreateAttachmentRequestDataAttributes'
@@ -13168,17 +13142,23 @@ components:
       - type
       type: object
     CreateAttachmentRequestDataAttributes:
+      description: The attributes for creating an attachment.
       properties:
         attachment:
           $ref: '#/components/schemas/CreateAttachmentRequestDataAttributesAttachment'
         attachment_type:
           $ref: '#/components/schemas/AttachmentDataAttributesAttachmentType'
       type: object
     CreateAttachmentRequestDataAttributesAttachment:
+      description: The attachment object for creating an attachment.
       properties:
         documentUrl:
+          description: The URL of the attachment.
+          example: https://app.datadoghq.com/notebook/123/Postmortem-IR-123
           type: string
         title:
+          description: The title of the attachment.
+          example: Postmortem-IR-123
           type: string
       type: object
     CreateCaseRequestArray:
@@ -42775,38 +42755,41 @@ components:
           type: array
       type: object
     PatchAttachmentRequest:
-      example:
-        data:
-          attributes:
-            attachment:
-              documentUrl: https://app.datadoghq.com/notebook/124/Postmortem-IR-124
-              title: Postmortem-IR-124
-          type: incident_attachments
+      description: Request to update an attachment.
       properties:
         data:
           $ref: '#/components/schemas/PatchAttachmentRequestData'
       type: object
     PatchAttachmentRequestData:
+      description: Attachment data for an update request.
       properties:
         attributes:
           $ref: '#/components/schemas/PatchAttachmentRequestDataAttributes'
         id:
+          description: The unique identifier of the attachment.
+          example: 00000000-abcd-0002-0000-000000000000
           type: string
         type:
           $ref: '#/components/schemas/IncidentAttachmentType'
       required:
       - type
       type: object
     PatchAttachmentRequestDataAttributes:
+      description: The attributes for updating an attachment.
       properties:
         attachment:
           $ref: '#/components/schemas/PatchAttachmentRequestDataAttributesAttachment'
       type: object
     PatchAttachmentRequestDataAttributesAttachment:
+      description: The updated attachment object.
       properties:
         documentUrl:
+          description: The updated URL for the attachment.
+          example: https://app.datadoghq.com/notebook/124/Postmortem-IR-124
           type: string
         title:
+          description: The updated title for the attachment.
+          example: Postmortem-IR-124
           type: string
       type: object
     PatchComponentRequest:
@@ -62229,17 +62212,6 @@ components:
         type:
           $ref: '#/components/schemas/UsersType'
       type: object
-    User140420082644000:
-      properties:
-        attributes:
-          $ref: '#/components/schemas/UserAttributes'
-        id:
-          type: string
-        type:
-          $ref: '#/components/schemas/UserType'
-      required:
-      - type
-      type: object
     UserAttributes:
       description: Attributes of user object returned by the API.
       properties:
@@ -62690,15 +62662,6 @@ components:
         meta:
           $ref: '#/components/schemas/TeamsResponseMeta'
       type: object
-    UserType:
-      default: users
-      description: Users resource type.
-      enum:
-      - users
-      example: users
-      type: string
-      x-enum-varnames:
-      - USERS
     UserUpdateAttributes:
       description: Attributes of the edited user.
       properties:
@@ -74906,12 +74869,7 @@ paths:
       operationId: DeleteIncidentAttachment
       parameters:
       - $ref: '#/components/parameters/IncidentIDPathParameter'
-      - description: The ID of the attachment.
-        in: path
-        name: attachment_id
-        required: true
-        schema:
-          example: 00000000-0000-0000-0000-000000000002
+      - $ref: '#/components/parameters/AttachmentIDPathParameter'
       responses:
         '204':
           description: No Content
@@ -74942,12 +74900,7 @@ paths:
       operationId: UpdateIncidentAttachment
       parameters:
       - $ref: '#/components/parameters/IncidentIDPathParameter'
-      - description: The ID of the attachment.
-        in: path
-        name: attachment_id
-        required: true
-        schema:
-          example: 00000000-0000-0000-0000-000000000002
+      - $ref: '#/components/parameters/AttachmentIDPathParameter'
       - $ref: '#/components/parameters/AttachmentIncludeQueryParameter'
       requestBody:
         content:

docs/datadog_api_client.v2.model.rst

@@ -1320,20 +1320,6 @@ datadog\_api\_client.v2.model.attachment\_data\_relationships module
    :members:
    :show-inheritance:
 
-datadog\_api\_client.v2.model.attachment\_data\_relationships\_last\_modified\_by\_user module
-----------------------------------------------------------------------------------------------
-
-.. automodule:: datadog_api_client.v2.model.attachment_data_relationships_last_modified_by_user
-   :members:
-   :show-inheritance:
-
-datadog\_api\_client.v2.model.attachment\_data\_relationships\_last\_modified\_by\_user\_data module
-----------------------------------------------------------------------------------------------------
-
-.. automodule:: datadog_api_client.v2.model.attachment_data_relationships_last_modified_by_user_data
-   :members:
-   :show-inheritance:
-
 datadog\_api\_client.v2.model.attachment\_included module
 ---------------------------------------------------------
 
@@ -27437,13 +27423,6 @@ datadog\_api\_client.v2.model.user module
    :members:
    :show-inheritance:
 
-datadog\_api\_client.v2.model.user140420082644000 module
---------------------------------------------------------
-
-.. automodule:: datadog_api_client.v2.model.user140420082644000
-   :members:
-   :show-inheritance:
-
 datadog\_api\_client.v2.model.user\_attributes module
 -----------------------------------------------------
 
@@ -27710,13 +27689,6 @@ datadog\_api\_client.v2.model.user\_teams\_response module
    :members:
    :show-inheritance:
 
-datadog\_api\_client.v2.model.user\_type module
------------------------------------------------
-
-.. automodule:: datadog_api_client.v2.model.user_type
-   :members:
-   :show-inheritance:
-
 datadog\_api\_client.v2.model.user\_update\_attributes module
 -------------------------------------------------------------
 

examples/v2/incidents/CreateIncidentAttachment.py

@@ -2,6 +2,7 @@
 Create incident attachment returns "Created" response
 """
 
+from os import environ
 from datadog_api_client import ApiClient, Configuration
 from datadog_api_client.v2.api.incidents_api import IncidentsApi
 from datadog_api_client.v2.model.attachment_data_attributes_attachment_type import (
@@ -15,16 +16,18 @@
 )
 from datadog_api_client.v2.model.incident_attachment_type import IncidentAttachmentType
 
+# there is a valid "incident" in the system
+INCIDENT_DATA_ID = environ["INCIDENT_DATA_ID"]
+
 body = CreateAttachmentRequest(
     data=CreateAttachmentRequestData(
         attributes=CreateAttachmentRequestDataAttributes(
             attachment=CreateAttachmentRequestDataAttributesAttachment(
-                document_url="https://app.datadoghq.com/notebook/123/Postmortem-IR-123",
-                title="Postmortem-IR-123",
+                document_url="https://app.datadoghq.com/notebook/ExampleIncident/Example-Incident",
+                title="Example-Incident",
             ),
             attachment_type=AttachmentDataAttributesAttachmentType.POSTMORTEM,
         ),
-        id="00000000-0000-0000-0000-000000000000",
         type=IncidentAttachmentType.INCIDENT_ATTACHMENTS,
     ),
 )
@@ -33,6 +36,6 @@
 configuration.unstable_operations["create_incident_attachment"] = True
 with ApiClient(configuration) as api_client:
     api_instance = IncidentsApi(api_client)
-    response = api_instance.create_incident_attachment(incident_id="incident_id", body=body)
+    response = api_instance.create_incident_attachment(incident_id=INCIDENT_DATA_ID, body=body)
 
     print(response)