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

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:

examples/v2/incidents/CreateIncidentAttachment.java

@@ -17,6 +17,9 @@ public static void main(String[] args) {
     defaultClient.setUnstableOperationEnabled("v2.createIncidentAttachment", true);
     IncidentsApi apiInstance = new IncidentsApi(defaultClient);
 
+    // there is a valid "incident" in the system
+    String INCIDENT_DATA_ID = System.getenv("INCIDENT_DATA_ID");
+
     CreateAttachmentRequest body =
         new CreateAttachmentRequest()
             .data(
@@ -26,14 +29,13 @@ public static void main(String[] args) {
                             .attachment(
                                 new CreateAttachmentRequestDataAttributesAttachment()
                                     .documentUrl(
-                                        "https://app.datadoghq.com/notebook/123/Postmortem-IR-123")
-                                    .title("Postmortem-IR-123"))
+                                        "https://app.datadoghq.com/notebook/ExampleIncident/Example-Incident")
+                                    .title("Example-Incident"))
                             .attachmentType(AttachmentDataAttributesAttachmentType.POSTMORTEM))
-                    .id("00000000-0000-0000-0000-000000000000")
                     .type(IncidentAttachmentType.INCIDENT_ATTACHMENTS));
 
     try {
-      Attachment result = apiInstance.createIncidentAttachment("incident_id", body);
+      Attachment result = apiInstance.createIncidentAttachment(INCIDENT_DATA_ID, body);
       System.out.println(result);
     } catch (ApiException e) {
       System.err.println("Exception when calling IncidentsApi#createIncidentAttachment");

examples/v2/incidents/DeleteIncidentAttachment.java

@@ -10,8 +10,14 @@ public static void main(String[] args) {
     defaultClient.setUnstableOperationEnabled("v2.deleteIncidentAttachment", true);
     IncidentsApi apiInstance = new IncidentsApi(defaultClient);
 
+    // there is a valid "incident" in the system
+    String INCIDENT_DATA_ID = System.getenv("INCIDENT_DATA_ID");
+
+    // there is a valid "incident_attachment" in the system
+    String INCIDENT_ATTACHMENT_DATA_ID = System.getenv("INCIDENT_ATTACHMENT_DATA_ID");
+
     try {
-      apiInstance.deleteIncidentAttachment("incident_id", "00000000-0000-0000-0000-000000000002");
+      apiInstance.deleteIncidentAttachment(INCIDENT_DATA_ID, INCIDENT_ATTACHMENT_DATA_ID);
     } catch (ApiException e) {
       System.err.println("Exception when calling IncidentsApi#deleteIncidentAttachment");
       System.err.println("Status code: " + e.getCode());

examples/v2/incidents/ListIncidentAttachments.java

@@ -11,8 +11,11 @@ public static void main(String[] args) {
     defaultClient.setUnstableOperationEnabled("v2.listIncidentAttachments", true);
     IncidentsApi apiInstance = new IncidentsApi(defaultClient);
 
+    // there is a valid "incident" in the system
+    String INCIDENT_DATA_ID = System.getenv("INCIDENT_DATA_ID");
+
     try {
-      AttachmentArray result = apiInstance.listIncidentAttachments("incident_id");
+      AttachmentArray result = apiInstance.listIncidentAttachments(INCIDENT_DATA_ID);
       System.out.println(result);
     } catch (ApiException e) {
       System.err.println("Exception when calling IncidentsApi#listIncidentAttachments");

examples/v2/incidents/UpdateIncidentAttachment.java

@@ -16,6 +16,12 @@ public static void main(String[] args) {
     defaultClient.setUnstableOperationEnabled("v2.updateIncidentAttachment", true);
     IncidentsApi apiInstance = new IncidentsApi(defaultClient);
 
+    // there is a valid "incident" in the system
+    String INCIDENT_DATA_ID = System.getenv("INCIDENT_DATA_ID");
+
+    // there is a valid "incident_attachment" in the system
+    String INCIDENT_ATTACHMENT_DATA_ID = System.getenv("INCIDENT_ATTACHMENT_DATA_ID");
+
     PatchAttachmentRequest body =
         new PatchAttachmentRequest()
             .data(
@@ -25,14 +31,14 @@ public static void main(String[] args) {
                             .attachment(
                                 new PatchAttachmentRequestDataAttributesAttachment()
                                     .documentUrl(
-                                        "https://app.datadoghq.com/notebook/124/Postmortem-IR-124")
-                                    .title("Postmortem-IR-124")))
+                                        "https://app.datadoghq.com/notebook/124/Example-Incident")
+                                    .title("Example-Incident")))
+                    .id(INCIDENT_ATTACHMENT_DATA_ID)
                     .type(IncidentAttachmentType.INCIDENT_ATTACHMENTS));
 
     try {
       Attachment result =
-          apiInstance.updateIncidentAttachment(
-              "incident_id", "00000000-0000-0000-0000-000000000002", body);
+          apiInstance.updateIncidentAttachment(INCIDENT_DATA_ID, INCIDENT_ATTACHMENT_DATA_ID, body);
       System.out.println(result);
     } catch (ApiException e) {
       System.err.println("Exception when calling IncidentsApi#updateIncidentAttachment");