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

@@ -13,10 +13,45 @@ responses:
     content:
       application/json:
         schema:
-          type: array
-          description: Array of all portals
-          items:
-            $ref: '#/components/schemas/portal'
+          $ref: '#/components/schemas/portal'
+        example:
+          payload:
+            - id: 4
+              color: "#1F93FF"
+              custom_domain: "chatwoot.help"
+              header_text: "Handbook"
+              homepage_link: "https://www.chatwoot.com"
+              name: "Handbook"
+              page_title: "Handbook"
+              slug: "handbook"
+              archived: false
+              account_id: 1
+              config:
+                allowed_locales:
+                  - code: "en"
+                    articles_count: 32
+                    categories_count: 9
+              inbox:
+                id: 37
+                avatar_url: "https://example.com/avatar.png"
+                channel_id: 1
+                name: "Chatwoot"
+                channel_type: "Channel::WebWidget"
+                greeting_enabled: true
+                widget_color: "#1F93FF"
+                website_url: "chatwoot.com"
+              logo:
+                id: 19399916
+                portal_id: 4
+                file_type: "image/png"
+                account_id: 1
+                file_url: "https://example.com/logo.png"
+                blob_id: 21239614
+                filename: "square.png"
+              meta:
+                all_articles_count: 0
+                categories_count: 9
+                default_locale: "en"
   '403':
     description: Access denied
     content:

swagger/paths/application/portal/show.yml

@@ -0,0 +1,79 @@
+tags:
+  - Help Center
+operationId: get-details-of-a-single-portal
+summary: Get a portal details
+description: Get the details of a portal in the account
+security:
+  - userApiKey: []
+parameters:
+  - $ref: '#/components/parameters/account_id'
+  - $ref: '#/components/parameters/portal_id'
+responses:
+  '200':
+    description: Success
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/portal_single'
+        example:
+          payload:
+            id: 123
+            archived: false
+            color: "#1F93FF"
+            config:
+              allowed_locales:
+                - code: "en"
+                  articles_count: 32
+                  categories_count: 9
+            custom_domain: "chatwoot.help"
+            header_text: "Handbook"
+            homepage_link: "https://www.chatwoot.com"
+            name: "Handbook"
+            slug: "handbook"
+            page_title: "Handbook"
+            account_id: 123
+            inbox:
+              id: 123
+              name: "Chatwoot"
+              website_url: "chatwoot.com"
+              channel_type: "Channel::WebWidget"
+              avatar_url: "https://example.com/avatar.png"
+              widget_color: "#1F93FF"
+              website_token: "4cWzuf9i9jxN9tbnv8K9STKU"
+              enable_auto_assignment: true
+              web_widget_script: "<script>...</script>"
+              welcome_title: "Hi there ! 🙌🏼"
+              welcome_tagline: "We make it simple to connect with us."
+              greeting_enabled: true
+              greeting_message: "Hey there 👋, Thank you for reaching out to us."
+              channel_id: 123
+              working_hours_enabled: true
+              enable_email_collect: true
+              csat_survey_enabled: true
+              timezone: "America/Los_Angeles"
+              business_name: "Chatwoot"
+              hmac_mandatory: true
+            logo:
+              id: 123
+              portal_id: 123
+              file_type: "image/png"
+              account_id: 123
+              file_url: "https://example.com/logo.png"
+              blob_id: 123
+              filename: "square.png"
+            meta:
+              all_articles_count: 32
+              categories_count: 9
+              default_locale: "en"
+  '401':
+    description: Unauthorized
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'
+  '404':
+    description: The given portal ID does not exist in the account
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error' 

swagger/paths/application/portal/update.yml

@@ -5,6 +5,9 @@ summary: Update a portal
 description: Update a portal to account
 security:
   - userApiKey: []
+parameters:
+  - $ref: '#/components/parameters/account_id'
+  - $ref: '#/components/parameters/portal_id'
 requestBody:
   required: true
   content:
@@ -17,10 +20,66 @@ responses:
     content:
       application/json:
         schema:
-          $ref: '#/components/schemas/portal'
+          $ref: '#/components/schemas/portal_single'
+        example:
+          payload:
+            id: 123
+            archived: false
+            color: "#1F93FF"
+            config:
+              allowed_locales:
+                - code: "en"
+                  articles_count: 32
+                  categories_count: 9
+            custom_domain: "chatwoot.help"
+            header_text: "Handbook"
+            homepage_link: "https://www.chatwoot.com"
+            name: "Handbook"
+            slug: "handbook"
+            page_title: "Handbook"
+            account_id: 123
+            inbox:
+              id: 123
+              name: "Chatwoot"
+              website_url: "chatwoot.com"
+              channel_type: "Channel::WebWidget"
+              avatar_url: "https://example.com/avatar.png"
+              widget_color: "#1F93FF"
+              website_token: "4cWzuf9i9jxN9tbnv8K9STKU"
+              enable_auto_assignment: true
+              web_widget_script: "<script>...</script>"
+              welcome_title: "Hi there ! 🙌🏼"
+              welcome_tagline: "We make it simple to connect with us."
+              greeting_enabled: true
+              greeting_message: "Hey there 👋, Thank you for reaching out to us."
+              channel_id: 123
+              working_hours_enabled: true
+              enable_email_collect: true
+              csat_survey_enabled: true
+              timezone: "America/Los_Angeles"
+              business_name: "Chatwoot"
+              hmac_mandatory: true
+            logo:
+              id: 123
+              portal_id: 123
+              file_type: "image/png"
+              account_id: 123
+              file_url: "https://example.com/logo.png"
+              blob_id: 123
+              filename: "square.png"
+            meta:
+              all_articles_count: 32
+              categories_count: 9
+              default_locale: "en"
   '403':
     description: Access denied
     content:
       application/json:
         schema:
           $ref: '#/components/schemas/bad_request_error'
+  '404':
+    description: Portal not found
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/bad_request_error'