LeadMagnet/leadchat
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

feat: validate OpenAPI spec using Skooma (#13623)

Browse Source 
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>
This commit is contained in:
Shivam Mishra
2026-03-11 07:03:55 +05:30
committed by GitHub
parent dc0e5eb465
commit 9a9398b386
54 changed files with 3216 additions and 1192 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
swagger/definitions/resource/account_detail.yml
View File

@@ -26,9 +26,7 @@ properties:
type: object
description: Cache keys for the account
features:
type: array
items:
type: string
type: object
description: Enabled features for the account
settings:
type: object
@@ -48,16 +46,24 @@ properties:
description: Custom attributes of the account
properties:
plan_name:
type: string
type:
- string
- 'null'
description: Subscription plan name
subscribed_quantity:
type: number
type:
- number
- 'null'
description: Subscribed quantity
subscription_status:
type: string
type:
- string
- 'null'
description: Subscription status
subscription_ends_on:
type: string
type:
- string
- 'null'
format: date
description: Subscription end date
industry:

4
swagger/definitions/resource/account_show_response.yml
View File

@@ -3,7 +3,9 @@ allOf:
- type: object
properties:
latest_chatwoot_version:
type: string
type:
- string
- 'null'
description: Latest version of Chatwoot available
example: "3.0.0"
subscribed_features:

4
swagger/definitions/resource/agent.yml
View File

@@ -31,5 +31,7 @@ properties:
type: string
description: The thumbnail of the agent
custom_role_id:
type: integer
type:
- integer
- 'null'
description: The custom role id of the agent

10
swagger/definitions/resource/audit_log.yml
View File

@@ -38,8 +38,9 @@ properties:
type: integer
description: Version number of the audit log entry
comment:
type: string
nullable: true
type:
- string
- 'null'
description: Optional comment associated with the audit log entry
request_uuid:
type: string
@@ -48,6 +49,7 @@ properties:
type: integer
description: Unix timestamp when the audit log entry was created
remote_address:
type: string
nullable: true
type:
- string
- 'null'
description: IP address from which the action was performed

25
swagger/definitions/resource/contact_conversation_message.yml
View File

@@ -31,9 +31,10 @@ properties:
type: string
description: Status of the message
source_id:
type: string
type:
- string
- 'null'
description: Source ID of the message
nullable: true
content_type:
type: string
description: Type of the content
@@ -41,13 +42,15 @@ properties:
type: object
description: Attributes of the content
sender_type:
type: string
type:
- string
- 'null'
description: Type of the sender
nullable: true
sender_id:
type: integer
type:
- integer
- 'null'
description: ID of the sender
nullable: true
external_source_ids:
type: object
description: External source IDs
@@ -55,9 +58,10 @@ properties:
type: object
description: Additional attributes of the message
processed_message_content:
type: string
type:
- string
- 'null'
description: Processed message content
nullable: true
sentiment:
type: object
description: Sentiment analysis of the message
@@ -66,9 +70,10 @@ properties:
description: Conversation details
properties:
assignee_id:
type: integer
type:
- integer
- 'null'
description: ID of the assignee
nullable: true
unread_count:
type: integer
description: Count of unread messages

14
swagger/definitions/resource/contact_detail.yml
View File

@@ -11,7 +11,9 @@ properties:
type: string
description: Country of the contact
country_code:
type: string
type:
- string
- 'null'
description: Country code of the contact
created_at_ip:
type: string
@@ -26,16 +28,18 @@ properties:
type: integer
description: The ID of the contact
identifier:
type: string
type:
- string
- 'null'
description: The identifier of the contact
nullable: true
name:
type: string
description: The name of the contact
phone_number:
type: string
type:
- string
- 'null'
description: The phone number of the contact
nullable: true
thumbnail:
type: string
description: The thumbnail of the contact

7
swagger/definitions/resource/contact_inbox.yml
View File

@@ -22,6 +22,7 @@ properties:
type: string
description: Type of channel
provider:
type: string
description: Provider of the inbox
nullable: true
type:
- string
- 'null'
description: Provider of the inbox

24
swagger/definitions/resource/contact_list_item.yml
View File

@@ -11,7 +11,9 @@ properties:
type: string
description: Country of the contact
country_code:
type: string
type:
- string
- 'null'
description: Country code of the contact
created_at_ip:
type: string
@@ -21,9 +23,10 @@ properties:
description: Availability status of the contact
enum: ["online", "offline"]
email:
type: string
type:
- string
- 'null'
description: The email address of the contact
nullable: true
id:
type: integer
description: The ID of the contact
@@ -31,16 +34,18 @@ properties:
type: string
description: The name of the contact
phone_number:
type: string
type:
- string
- 'null'
description: The phone number of the contact
nullable: true
blocked:
type: boolean
description: Whether the contact is blocked
identifier:
type: string
type:
- string
- 'null'
description: The identifier of the contact
nullable: true
thumbnail:
type: string
description: The thumbnail of the contact
@@ -48,9 +53,10 @@ properties:
type: object
description: The custom attributes of the contact
last_activity_at:
type: integer
type:
- integer
- 'null'
description: Timestamp of last activity
nullable: true
created_at:
type: integer
description: Timestamp when contact was created

6
swagger/definitions/resource/contact_meta.yml
View File

@@ -4,5 +4,7 @@ properties:
type: integer
description: Total number of contacts
current_page:
type: string
description: Current page number
type:
- string
- integer
description: Current page number

27
swagger/definitions/resource/conversation.yml
View File

@@ -43,7 +43,9 @@ properties:
type: boolean
description: Whether the conversation is muted
snoozed_until:
type: number
type:
- number
- 'null'
description: The time at which the conversation will be unmuted
status:
type: string
@@ -56,29 +58,38 @@ properties:
type: number
description: The time at which conversation was updated
timestamp:
type: string
type: number
description: The time at which conversation was created
first_reply_created_at:
type: number
type:
- number
- 'null'
description: The time at which the first reply was created
unread_count:
type: number
description: The number of unread messages
last_non_activity_message:
type: object
$ref: '#/components/schemas/message'
oneOf:
- $ref: '#/components/schemas/message'
- type: 'null'
description: The last non activity message
last_activity_at:
type: number
description: The last activity at of the conversation
priority:
type: string
type:
- string
- 'null'
description: The priority of the conversation
waiting_since:
type: number
type:
- number
- 'null'
description: The time at which the conversation was waiting
sla_policy_id:
type: number
type:
- number
- 'null'
description: The ID of the SLA policy
applied_sla:
type: object

12
swagger/definitions/resource/conversation_meta.yml
View File

@@ -51,10 +51,12 @@ properties:
description: The agent assigned to the conversation
nullable: true
agent_last_seen_at:
type: string
type:
- string
- 'null'
description: Timestamp when the agent last saw the conversation
nullable: true
assignee_last_seen_at:
type: string
description: Timestamp when the assignee last saw the conversation
nullable: true
type:
- string
- 'null'
description: Timestamp when the assignee last saw the conversation

16
swagger/definitions/resource/extension/contact/conversation.yml
View File

@@ -13,7 +13,9 @@ properties:
type: string
description: The availability status of the sender
email:
type: string
type:
- string
- 'null'
description: The email of the sender
id:
type: number
@@ -22,16 +24,22 @@ properties:
type: string
description: The name of the sender
phone_number:
type: string
type:
- string
- 'null'
description: The phone number of the sender
blocked:
type: boolean
description: Whether the sender is blocked
identifier:
type: string
type:
- string
- 'null'
description: The identifier of the sender
thumbnail:
type: string
type:
- string
- 'null'
description: Avatar URL of the contact
custom_attributes:
type: object

58
swagger/definitions/resource/inbox.yml
View File

@@ -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

48
swagger/definitions/resource/message.yml
View File

@@ -17,37 +17,49 @@ properties:
description: The ID of the conversation
message_type:
type: integer
enum: [0, 1, 2]
enum: [0, 1, 2, 3]
description: The type of the message
created_at:
type: integer
description: The time at which message was created
updated_at:
type: integer
type:
- integer
- string
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"]
type:
- string
- 'null'
enum: ["sent", "delivered", "read", "failed", null]
description: The status of the message
source_id:
type: string
type:
- string
- 'null'
description: The source ID of the message
content_type:
type: string
enum: ["text", "input_select", "cards", "form"]
type:
- string
- 'null'
enum: ["text", "input_text", "input_textarea", "input_email", "input_select", "cards", "form", "article", "incoming_email", "input_csat", "integrations", "sticker", "voice_call", null]
description: The type of the template message
content_attributes:
type: object
description: The content attributes for each content_type
sender_type:
type: string
enum: ["contact", "agent", "agent_bot"]
type:
- string
- 'null'
enum: ["Contact", "User", "AgentBot", "Captain::Assistant", null]
description: The type of the sender
sender_id:
type: number
type:
- number
- 'null'
description: The ID of the sender
external_source_ids:
type: object
@@ -56,16 +68,24 @@ properties:
type: object
description: The additional attributes of the message
processed_message_content:
type: string
type:
- string
- 'null'
description: The processed message content
sentiment:
type: object
type:
- object
- 'null'
description: The sentiment of the message
conversation:
type: object
type:
- object
- 'null'
description: The conversation object
attachment:
type: object
type:
- object
- 'null'
description: The file object attached to the image
sender:
type: object

19
swagger/definitions/resource/message_detailed.yml
View File

@@ -18,7 +18,7 @@ properties:
description: "The type of the message (0: incoming, 1: outgoing, 2: activity, 3: template)"
content_type:
type: string
enum: ["text", "input_select", "cards", "form", "input_csat"]
enum: ["text", "input_text", "input_textarea", "input_email", "input_select", "cards", "form", "article", "incoming_email", "input_csat", "integrations", "sticker", "voice_call"]
description: The type of the message content
status:
type: string
@@ -29,13 +29,15 @@ properties:
description: The content attributes for each content_type
properties:
in_reply_to:
type: string
type:
- string
- 'null'
description: ID of the message this is replying to
nullable: true
echo_id:
type: string
type:
- string
- 'null'
description: The echo ID of the message, used for deduplication
nullable: true
created_at:
type: integer
description: The timestamp when message was created
@@ -43,9 +45,10 @@ properties:
type: boolean
description: The flag which shows whether the message is private or not
source_id:
type: string
type:
- string
- 'null'
description: The source ID of the message
nullable: true
sender:
$ref: '#/components/schemas/contact_detail'
description: The sender of the message (only for incoming messages)
@@ -76,4 +79,4 @@ properties:
description: The thumbnail URL of the attached file
file_size:
type: number
description: The size of the attached file in bytes
description: The size of the attached file in bytes

15
swagger/definitions/resource/portal_meta.yml
View File

@@ -4,16 +4,19 @@ properties:
type: integer
description: Total number of articles
archived_articles_count:
type: integer
nullable: true
type:
- integer
- 'null'
description: Number of archived articles
published_count:
type: integer
nullable: true
type:
- integer
- 'null'
description: Number of published articles
draft_articles_count:
type: integer
nullable: true
type:
- integer
- 'null'
description: Number of draft articles
categories_count:
type: integer

15
swagger/definitions/resource/reporting_event.yml
View File

@@ -26,16 +26,19 @@ properties:
type: number
description: ID of the account
conversation_id:
type: number
nullable: true
type:
- number
- 'null'
description: ID of the conversation
inbox_id:
type: number
nullable: true
type:
- number
- 'null'
description: ID of the inbox
user_id:
type: number
nullable: true
type:
- number
- 'null'
description: ID of the user/agent
created_at:
type: string

15
swagger/definitions/resource/reports/agent_summary.yml
View File

@@ -13,16 +13,19 @@ items:
type: number
description: Number of conversations resolved by the agent during the date range
avg_resolution_time:
type: number
nullable: true
type:
- number
- 'null'
description: Average time (in seconds) to resolve conversations. Null if no data available.
avg_first_response_time:
type: number
nullable: true
type:
- number
- 'null'
description: Average time (in seconds) for the first response. Null if no data available.
avg_reply_time:
type: number
nullable: true
type:
- number
- 'null'
description: Average time (in seconds) between replies. Null if no data available.
example:
- id: 1

15
swagger/definitions/resource/reports/inbox_summary.yml
View File

@@ -13,16 +13,19 @@ items:
type: number
description: Number of conversations resolved in the inbox during the date range
avg_resolution_time:
type: number
nullable: true
type:
- number
- 'null'
description: Average time (in seconds) to resolve conversations. Null if no data available.
avg_first_response_time:
type: number
nullable: true
type:
- number
- 'null'
description: Average time (in seconds) for the first response. Null if no data available.
avg_reply_time:
type: number
nullable: true
type:
- number
- 'null'
description: Average time (in seconds) between replies. Null if no data available.
example:
- id: 1

15
swagger/definitions/resource/reports/team_summary.yml
View File

@@ -13,16 +13,19 @@ items:
type: number
description: Number of conversations resolved by the team during the date range
avg_resolution_time:
type: number
nullable: true
type:
- number
- 'null'
description: Average time (in seconds) to resolve conversations. Null if no data available.
avg_first_response_time:
type: number
nullable: true
type:
- number
- 'null'
description: Average time (in seconds) for the first response. Null if no data available.
avg_reply_time:
type: number
nullable: true
type:
- number
- 'null'
description: Average time (in seconds) between replies. Null if no data available.
example:
- id: 1

4
swagger/definitions/resource/team.yml
View File

@@ -7,7 +7,9 @@ properties:
type: string
description: The name of the team
description:
type: string
type:
- string
- 'null'
description: The description about the team
allow_auto_assign:
type: boolean

33
swagger/definitions/resource/user.yml
View File

@@ -13,17 +13,21 @@ properties:
confirmed:
type: boolean
display_name:
type: string
nullable: true
type:
- string
- 'null'
message_signature:
type: string
nullable: true
type:
- string
- 'null'
email:
type: string
hmac_identifier:
type: string
inviter_id:
type: number
type:
- number
- 'null'
name:
type: string
provider:
@@ -38,8 +42,9 @@ properties:
uid:
type: string
type:
type: string
nullable: true
type:
- string
- 'null'
custom_attributes:
type: object
description: Available for users who are created through platform APIs and has custom attributes associated.
@@ -55,7 +60,9 @@ properties:
status:
type: string
active_at:
type: string
type:
- string
- 'null'
format: date-time
role:
type: string
@@ -71,8 +78,10 @@ properties:
auto_offline:
type: boolean
custom_role_id:
type: number
nullable: true
type:
- number
- 'null'
custom_role:
type: object
nullable: true
type:
- object
- 'null'