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/index.yml

@@ -16,8 +16,20 @@ custom_attribute:
   $ref: ./resource/custom_attribute.yml
 automation_rule:
   $ref: ./resource/automation_rule.yml
+automation_rule_item:
+  $ref: ./resource/automation_rule_item.yml
 portal:
   $ref: ./resource/portal.yml
+portal_single:
+  $ref: ./resource/portal_single.yml
+portal_config:
+  $ref: ./resource/portal_config.yml
+portal_logo:
+  $ref: ./resource/portal_logo.yml
+portal_meta:
+  $ref: ./resource/portal_meta.yml
+portal_item:
+  $ref: ./resource/portal_item.yml
 category:
   $ref: ./resource/category.yml
 article:
@@ -34,6 +46,8 @@ agent:
   $ref: ./resource/agent.yml
 inbox:
   $ref: ./resource/inbox.yml
+inbox_contact:
+  $ref: ./resource/inbox_contact.yml
 agent_bot:
   $ref: ./resource/agent_bot.yml
 contact_inboxes:
@@ -173,7 +187,6 @@ contact_list:
   description: 'array of contacts'
   items:
     allOf:
-      - $ref: '#/components/schemas/generic_id'
       - $ref: '#/components/schemas/contact'
 contact_conversations:
   type: array
@@ -201,3 +214,28 @@ account_summary:
   $ref: './resource/reports/summary.yml'
 agent_conversation_metrics:
   $ref: './resource/reports/conversation/agent.yml'
+
+contact_detail:
+  $ref: ./resource/contact_detail.yml
+message_detailed:
+  $ref: ./resource/message_detailed.yml
+conversation_meta:
+  $ref: ./resource/conversation_meta.yml
+conversation_messages:
+  $ref: ./resource/conversation_messages.yml
+contact_meta:
+  $ref: ./resource/contact_meta.yml
+contact_inbox:
+  $ref: ./resource/contact_inbox.yml
+contact_list_item:
+  $ref: ./resource/contact_list_item.yml
+contacts_list_response:
+  $ref: ./resource/contacts_list_response.yml
+contact_show_response:
+  $ref: ./resource/contact_show_response.yml
+contact_conversation_message:
+  $ref: ./resource/contact_conversation_message.yml
+contact_conversations_response:
+  $ref: ./resource/contact_conversations_response.yml
+contactable_inboxes_response:
+  $ref: ./resource/contactable_inboxes_response.yml