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

@@ -2,27 +2,77 @@ type: object
 properties:
   id:
     type: number
-  uid:
-    type: string
-  name:
-    type: string
-  available_name:
-    type: string
-  display_name:
-    type: string
-  email:
+  access_token:
     type: string
   account_id:
     type: number
+  available_name:
+    type: string
+  avatar_url:
+    type: string
+  confirmed:
+    type: boolean
+  display_name:
+    type: string
+    nullable: true
+  message_signature:
+    type: string
+    nullable: true
+  email:
+    type: string
+  hmac_identifier:
+    type: string
+  inviter_id:
+    type: number
+  name:
+    type: string
+  provider:
+    type: string
+  pubsub_token:
+    type: string
   role:
     type: string
     enum: ['agent', 'administrator']
-  confirmed:
-    type: boolean
+  ui_settings:
+    type: object
+  uid:
+    type: string
+  type:
+    type: string
+    nullable: true
   custom_attributes:
     type: object
     description: Available for users who are created through platform APIs and has custom attributes associated.
   accounts:
     type: array
     items:
-      $ref: '#/components/schemas/account'
+      type: object
+      properties:
+        id:
+          type: number
+        name:
+          type: string
+        status:
+          type: string
+        active_at:
+          type: string
+          format: date-time
+        role:
+          type: string
+          enum: ['administrator', 'agent']
+        permissions:
+          type: array
+          items:
+            type: string
+        availability:
+          type: string
+        availability_status:
+          type: string
+        auto_offline:
+          type: boolean
+        custom_role_id:
+          type: number
+          nullable: true
+        custom_role:
+          type: object
+          nullable: true