feat: Update swagger to openapi 3.0.4, update request payloads with examples (#11533)

# Pull Request Template

## Description

Updates the public swagger spec to be OpenAPI 3.0.4 compliant. Regarding
#7893, I'm investigating the use of
[oas_rails](https://github.com/a-chacon/oas_rails) to auto-generate the
documentation along with correct expected payloads.
Mostly fixes #10531, related to #7893

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality not to work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Copied spec into swagger editor, reviewed outputs:

![openapi](https://github.com/user-attachments/assets/bd43f895-74bb-4373-ba6d-c5b190b699dd)

Note that this shows two errors with the `DELETE` endpoints as
technically these should not have a `requestBody` - in which case we
should be making use of another HTTP verb or another endpoint.

## Checklist:

- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my code
- [x] I have commented on my code, particularly in hard-to-understand
areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] Any dependent changes have been merged and published in downstream
modules

---------

Co-authored-by: Daniel Jimenez <devildan.knex@gmail.com>
Co-authored-by: Daniel Jimenez <daniel.jimenez@spark64.com>

swagger/definitions/resource/message.yml

@@ -1,8 +1,40 @@
 type: object
 properties:
+  id:
+    type: number
+    description: The ID of the message
   content:
     type: string
     description: The text content of the message
+  account_id:
+    type: number
+    description: The ID of the account
+  inbox_id:
+    type: number
+    description: The ID of the inbox
+  conversation_id:
+    type: number
+    description: The ID of the conversation
+  message_type:
+    type: integer
+    enum: [0, 1, 2]
+    description: The type of the message
+  created_at:
+    type: integer
+    description: The time at which message was created
+  updated_at:
+    type: integer
+    description: The time at which message was updated
+  private:
+    type: boolean
+    description: The flags which shows whether the message is private or not
+  status:
+    type: string
+    enum: ["sent", "delivered", "read", "failed"]
+    description: The status of the message
+  source_id:
+    type: string
+    description: The source ID of the message
   content_type:
     type: string
     enum: ["text", "input_select", "cards", "form"]
@@ -10,22 +42,31 @@ properties:
   content_attributes:
     type: object
     description: The content attributes for each content_type
-  message_type:
+  sender_type:
     type: string
-    enum: ["incoming", "outgoing", "activity", "template"]
-    description: The type of the message
-  created_at:
-    type: integer
-    description: The time at which message was created
-  private:
-    type: boolean
-    description: The flags which shows whether the message is private or not
+    enum: ["contact", "agent", "agent_bot"]
+    description: The type of the sender
+  sender_id:
+    type: number
+    description: The ID of the sender
+  external_source_ids:
+    type: object
+    description: The external source IDs of the message
+  additional_attributes:
+    type: object
+    description: The additional attributes of the message
+  processed_message_content:
+    type: string
+    description: The processed message content
+  sentiment:
+    type: object
+    description: The sentiment of the message
+  conversation:
+    type: object
+    description: The conversation object
   attachment:
     type: object
     description: The file object attached to the image
   sender:
     type: object
     description: User/Agent/AgentBot object
-  conversation_id:
-    type: number
-    description: ID of the conversation