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:  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>
This commit is contained in:
Tanmay Deep Sharma
committed by
GitHub
GitHub
parent
99de5f4257
commit
459f225559
@@ -14,10 +14,7 @@ responses:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
description: Array of all automation rules
|
||||
items:
|
||||
$ref: '#/components/schemas/automation_rule'
|
||||
$ref: '#/components/schemas/automation_rule'
|
||||
'403':
|
||||
description: Access denied
|
||||
content:
|
||||
|
||||
@@ -19,6 +19,26 @@ responses:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/automation_rule'
|
||||
example:
|
||||
payload:
|
||||
id: 90
|
||||
account_id: 1
|
||||
name: "add-label-bug-if-message-contains-bug"
|
||||
description: "add-label-bug-if-message-contains-bug"
|
||||
event_name: "message_created"
|
||||
conditions:
|
||||
- values: ["incoming"]
|
||||
attribute_key: "message_type"
|
||||
query_operator: "and"
|
||||
filter_operator: "equal_to"
|
||||
- values: ["bug"]
|
||||
attribute_key: "content"
|
||||
filter_operator: "contains"
|
||||
actions:
|
||||
- action_name: "add_label"
|
||||
action_params: ["bugs", "support-query"]
|
||||
created_on: 1650555440
|
||||
active: true
|
||||
'401':
|
||||
description: Unauthorized
|
||||
content:
|
||||
|
||||
@@ -20,7 +20,7 @@ get:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/contactable_inboxes'
|
||||
$ref: '#/components/schemas/contactable_inboxes_response'
|
||||
'401':
|
||||
description: Authentication error
|
||||
content:
|
||||
|
||||
@@ -28,7 +28,7 @@ get:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/contact_conversations'
|
||||
$ref: '#/components/schemas/contact_conversations_response'
|
||||
'404':
|
||||
description: Contact not found
|
||||
content:
|
||||
|
||||
@@ -21,7 +21,7 @@ get:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/extended_contact'
|
||||
$ref: '#/components/schemas/contact_show_response'
|
||||
'404':
|
||||
description: Contact not found
|
||||
content:
|
||||
|
||||
@@ -55,7 +55,7 @@ post:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/contact_list'
|
||||
$ref: '#/components/schemas/contacts_list_response'
|
||||
'400':
|
||||
description: Bad Request Error
|
||||
content:
|
||||
|
||||
@@ -9,7 +9,7 @@ parameters:
|
||||
|
||||
get:
|
||||
tags:
|
||||
- Contacts
|
||||
- Contact Labels
|
||||
operationId: list-all-labels-of-a-contact
|
||||
summary: List Labels
|
||||
description: Lists all the labels of a contact
|
||||
@@ -37,7 +37,7 @@ get:
|
||||
|
||||
post:
|
||||
tags:
|
||||
- Contacts
|
||||
- Contact Labels
|
||||
operationId: contact-add-labels
|
||||
summary: Add Labels
|
||||
description: Add labels to a contact. Note that this API would overwrite the existing list of labels associated to the conversation.
|
||||
|
||||
@@ -16,7 +16,7 @@ get:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/contact_list'
|
||||
$ref: '#/components/schemas/contacts_list_response'
|
||||
'400':
|
||||
description: Bad Request Error
|
||||
content:
|
||||
|
||||
@@ -21,10 +21,7 @@ get:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
payload:
|
||||
$ref: '#/components/schemas/contact_list'
|
||||
$ref: '#/components/schemas/contacts_list_response'
|
||||
'401':
|
||||
description: Authentication error
|
||||
content:
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
tags:
|
||||
- Conversations
|
||||
- Conversation Assignments
|
||||
operationId: assign-a-conversation
|
||||
summary: Assign Conversation
|
||||
description: Assign a conversation to an agent or a team
|
||||
|
||||
@@ -11,12 +11,32 @@ responses:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
description: Array of messages
|
||||
items:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/generic_id'
|
||||
- $ref: '#/components/schemas/message'
|
||||
type: object
|
||||
properties:
|
||||
meta:
|
||||
type: object
|
||||
properties:
|
||||
labels:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
additional_attributes:
|
||||
type: object
|
||||
contact:
|
||||
$ref: '#/components/schemas/contact'
|
||||
assignee:
|
||||
$ref: '#/components/schemas/agent'
|
||||
agent_last_seen_at:
|
||||
type: string
|
||||
format: date-time
|
||||
assignee_last_seen_at:
|
||||
type: string
|
||||
format: date-time
|
||||
payload:
|
||||
type: array
|
||||
description: Array of messages
|
||||
items:
|
||||
$ref: '#/components/schemas/message'
|
||||
'404':
|
||||
description: Conversation not found
|
||||
content:
|
||||
|
||||
@@ -31,10 +31,13 @@ responses:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
description: 'Array of all active agents'
|
||||
items:
|
||||
$ref: '#/components/schemas/agent'
|
||||
type: object
|
||||
properties:
|
||||
payload:
|
||||
type: array
|
||||
description: 'Array of all active agents'
|
||||
items:
|
||||
$ref: '#/components/schemas/agent'
|
||||
'404':
|
||||
description: Inbox not found
|
||||
content:
|
||||
|
||||
@@ -13,10 +13,13 @@ responses:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
description: 'Array of all active agents'
|
||||
items:
|
||||
$ref: '#/components/schemas/agent'
|
||||
type: object
|
||||
properties:
|
||||
payload:
|
||||
type: array
|
||||
description: 'Array of all active agents'
|
||||
items:
|
||||
$ref: '#/components/schemas/agent'
|
||||
'404':
|
||||
description: Inbox not found
|
||||
content:
|
||||
|
||||
@@ -31,10 +31,13 @@ responses:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
description: 'Array of all active agents'
|
||||
items:
|
||||
$ref: '#/components/schemas/agent'
|
||||
type: object
|
||||
properties:
|
||||
payload:
|
||||
type: array
|
||||
description: 'Array of all active agents'
|
||||
items:
|
||||
$ref: '#/components/schemas/agent'
|
||||
'404':
|
||||
description: Inbox not found
|
||||
content:
|
||||
|
||||
@@ -14,10 +14,13 @@ get:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
description: 'Array of inboxes'
|
||||
items:
|
||||
$ref: '#/components/schemas/inbox'
|
||||
type: object
|
||||
properties:
|
||||
payload:
|
||||
type: array
|
||||
description: 'Array of inboxes'
|
||||
items:
|
||||
$ref: '#/components/schemas/inbox'
|
||||
'404':
|
||||
description: Inbox not found
|
||||
content:
|
||||
|
||||
@@ -11,10 +11,13 @@ responses:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
description: 'Array of Integration apps'
|
||||
items:
|
||||
$ref: '#/components/schemas/integrations_app'
|
||||
type: object
|
||||
properties:
|
||||
payload:
|
||||
type: array
|
||||
description: 'Array of Integration apps'
|
||||
items:
|
||||
$ref: '#/components/schemas/integrations_app'
|
||||
'401':
|
||||
description: Unauthorized
|
||||
content:
|
||||
|
||||
@@ -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:
|
||||
|
||||
79
swagger/paths/application/portal/show.yml
Normal file
79
swagger/paths/application/portal/show.yml
Normal file
@@ -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'
|
||||
@@ -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'
|
||||
|
||||
@@ -63,11 +63,6 @@
|
||||
- $ref: '#/components/parameters/platform_user_id'
|
||||
get:
|
||||
$ref: './platform/users/login.yml'
|
||||
/platform/api/v1/users/{id}/token:
|
||||
parameters:
|
||||
- $ref: '#/parameters/platform_user_id'
|
||||
post:
|
||||
$ref: './platform/users/token.yml'
|
||||
|
||||
# ---------------- end of platform path -----------#
|
||||
|
||||
@@ -605,3 +600,27 @@
|
||||
description: The numeric ID of the user
|
||||
get:
|
||||
$ref: './application/reports/conversation/agent.yml'
|
||||
|
||||
# Conversations Messages
|
||||
/accounts/{account_id}/conversations/{conversation_id}/messages:
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/account_id'
|
||||
- name: conversation_id
|
||||
in: path
|
||||
description: ID of the conversation
|
||||
required: true
|
||||
schema:
|
||||
type: number
|
||||
get:
|
||||
tags:
|
||||
- Conversation
|
||||
summary: Get messages from a conversation
|
||||
description: Returns all messages from a specific conversation
|
||||
operationId: getConversationMessages
|
||||
responses:
|
||||
'200':
|
||||
description: Success
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/conversation_messages'
|
||||
|
||||
Reference in New Issue
Block a user