feat: validate OpenAPI spec using Skooma (#13623)

Adds Skooma-based OpenAPI validation so SDK-facing request specs can
assert that documented request and response contracts match real Rails
behavior. This also upgrades the spec to OpenAPI 3.1 and fixes contract
drift uncovered while validating core application and platform
resources.

Closes
None

Why
We want CI to catch OpenAPI drift before it reaches SDK consumers. While
wiring validation in, this PR surfaced several mismatches between the
documented contract and what the Rails endpoints actually accept or
return.

What this change does
- Adds Skooma-backed OpenAPI validation to the request spec flow and a
dedicated OpenAPI validation spec.
- Migrates nullable schema definitions to OpenAPI 3.1-compatible unions.
- Updates core SDK-facing schemas and payloads across accounts,
contacts, conversations, inboxes, messages, teams, reporting events, and
platform account resources.
- Documents concrete runtime cases that were previously missing or
inaccurate, including nested `profile` update payloads, multipart avatar
uploads, required profile update bodies, nullable inbox feature flags,
and message sender types that include both `Captain::Assistant` and
senderless activity-style messages.
- Regenerates the committed Swagger JSON and tag-group artifacts used by
CI sync checks.

Validation
- `bundle exec rake swagger:build`
- `bundle exec rspec spec/swagger/openapi_spec.rb`

---------

Co-authored-by: Sojan Jose <sojan@pepalo.com>

swagger/definitions/resource/inbox.yml

@@ -28,16 +28,22 @@ properties:
     type: string
     description: Script used to load the website widget
   welcome_title:
-    type: string
+    type:
+      - string
+      - 'null'
     description: Welcome title to be displayed on the widget
   welcome_tagline:
-    type: string
+    type:
+      - string
+      - 'null'
     description: Welcome tagline to be displayed on the widget
   greeting_enabled:
     type: boolean
     description: The flag which shows whether greeting is enabled
   greeting_message:
-    type: string
+    type:
+      - string
+      - 'null'
     description: A greeting message when the user starts the conversation
   channel_id:
     type: number
@@ -55,7 +61,9 @@ properties:
     type: object
     description: Configuration settings for auto assignment
   out_of_office_message:
-    type: string
+    type:
+      - string
+      - 'null'
     description: Message to show when agents are out of office
   working_hours:
     type: array
@@ -70,16 +78,24 @@ properties:
           type: boolean
           description: Whether the inbox is closed for the entire day
         open_hour:
-          type: number
+          type:
+            - number
+            - 'null'
           description: Hour when inbox opens (0-23)
         open_minutes:
-          type: number
+          type:
+            - number
+            - 'null'
           description: Minutes of the hour when inbox opens (0-59)
         close_hour:
-          type: number
+          type:
+            - number
+            - 'null'
           description: Hour when inbox closes (0-23)
         close_minutes:
-          type: number
+          type:
+            - number
+            - 'null'
           description: Minutes of the hour when inbox closes (0-59)
         open_all_day:
           type: boolean
@@ -88,7 +104,9 @@ properties:
     type: string
     description: Timezone configuration for the inbox
   callback_webhook_url:
-    type: string
+    type:
+      - string
+      - 'null'
     description: Webhook URL for callbacks
   allow_messages_after_resolved:
     type: boolean
@@ -100,26 +118,38 @@ properties:
     type: string
     description: Type of sender name to display (e.g., friendly)
   business_name:
-    type: string
+    type:
+      - string
+      - 'null'
     description: Business name associated with the inbox
   hmac_mandatory:
     type: boolean
     description: Whether HMAC verification is mandatory
   selected_feature_flags:
-    type: object
+    type:
+      - array
+      - 'null'
     description: Selected feature flags for the inbox
+    items:
+      type: string
   reply_time:
     type: string
     description: Expected reply time
   messaging_service_sid:
-    type: string
+    type:
+      - string
+      - 'null'
     description: Messaging service SID for SMS providers
   phone_number:
-    type: string
+    type:
+      - string
+      - 'null'
     description: Phone number associated with the inbox
   medium:
     type: string
     description: Medium of communication (e.g., sms, email)
   provider:
-    type: string
+    type:
+      - string
+      - 'null'
     description: Provider of the channel