Chore: Document Conversation APIs in swagger (#552)

* Added the documentation for the conversation APIs - 8 endpoints
* Added descriptions for the existing endpoints
* Added new resource models and updated some parts of the contact API

swagger/paths/contact/conversations.yml

@@ -5,7 +5,7 @@ get:
     - name: id
       in: path
       type: number
-      description: ID of contact
+      description: id of the contact
       required: true
   responses:
     200:

swagger/paths/contact/crud.yml

@@ -5,7 +5,7 @@ get:
     - name: id
       in: path
       type: number
-      description: ID of contact
+      description: id of the contact
       required: true
   responses:
     200:
@@ -24,7 +24,7 @@ put:
     - name: id
       in: path
       type: number
-      description: ID of the contact
+      description: id of the contact
       required: true
     - name: data
       in: body

swagger/paths/contact/list_create.yml

@@ -1,7 +1,7 @@
 get:
   tags: [Contact]
-  description: Listing all contacts with pagination
-  summary: List contacts
+  description: Listing all the contacts with pagination
+  summary: List Contacts
   parameters:
     - name: query_hash
       in: query
@@ -18,7 +18,7 @@ get:
 
 post:
   tags: [Contact]
-  description: Create a contact
+  description: Create New Contact
   parameters:
     - name: data
       in: body

swagger/paths/conversation/assignments.yml

@@ -0,0 +1,27 @@
+post:
+  tags: [Conversation]
+  summary: Assign Conversation
+  description: Assign a conversation to an agent
+  parameters:
+    - name: id
+      in: path
+      type: number
+      description: id of the conversation
+      required: true
+    - name: data
+      in: body
+      required: true
+      schema:
+        type: object
+        properties:
+          assignee_id:
+            type: number
+  responses:
+    204:
+      description: Success
+      schema:
+        $ref: '#/definitions/user'
+    404:
+      description: Conversation not found
+    403:
+      description: Access denied

swagger/paths/conversation/crud.yml

@@ -0,0 +1,19 @@
+get:
+  tags: [Conversation]
+  summary: Conversation Details
+  description: Get all details regarding a conversation with all messages in the conversation
+  parameters:
+    - name: id
+      in: path
+      type: number
+      description: ID of Conversation
+      required: true
+  responses:
+    200:
+      description: Success
+      schema:
+        $ref: '#/definitions/conversation_show'
+    404:
+      description: Conversation not found
+    403:
+      description: Access denied

swagger/paths/conversation/labels.yml

@@ -0,0 +1,50 @@
+get:
+  tags: [Conversation]
+  summary: List Labels
+  description: Lists all the labels of a conversation
+  parameters:
+    - name: id
+      in: path
+      type: number
+      description: id of the conversation
+      required: true
+  responses:
+    200:
+      description: Success
+      schema:
+        $ref: '#/definitions/conversation_labels'
+    404:
+      description: Conversation not found
+    403:
+      description: Access denied
+
+post:
+  tags: [Conversation]
+  summary: Add Label
+  description: Creates a new label and associates it with the conversation
+  parameters:
+    - name: id
+      in: path
+      type: number
+      description: id of the conversation
+      required: true
+    - name: data
+      in: body
+      required: true
+      schema:
+        type: object
+        properties:
+          labels:
+            type: array
+            description: 'array of labels'
+            properties:
+              type: string
+  responses:
+    204:
+      description: Success
+      schema:
+        $ref: '#/definitions/conversation_labels'
+    404:
+      description: Conversation not found
+    403:
+      description: Access denied

swagger/paths/conversation/list.yml

@@ -0,0 +1,17 @@
+get:
+  tags: [Conversation]
+  description: List all the conversations with pagination
+  summary: Conversations List
+  parameters:
+    - name: query_hash
+      in: query
+      type: string
+  responses:
+    200:
+      description: Success
+      schema:
+        $ref: '#/definitions/conversation_list'
+    400:
+      description: Bad Request Error
+      schema:
+        $ref: '#/definitions/bad_request_error'

swagger/paths/conversation/messages.yml

@@ -0,0 +1,26 @@
+post:
+  tags: [Conversation]
+  summary: Create New Message
+  description: All the agent replies are created as new messages through this endpoint
+  parameters:
+    - name: id
+      in: path
+      type: number
+      description: id of the conversation
+      required: true
+    - name: data
+      in: body
+      required: true
+      schema:
+        $ref: '#/definitions/conversation_message_create'
+  responses:
+    204:
+      description: Success
+      schema:
+        allOf:
+          - $ref: '#/definitions/generic_id'
+          - $ref: '#/definitions/message'
+    404:
+      description: Conversation not found
+    403:
+      description: Access denied

swagger/paths/conversation/toggle_status.yml

@@ -0,0 +1,19 @@
+post:
+  tags: [Conversation]
+  summary: Toggle Status
+  description: Toggles the status of the conversation between open and resolved
+  parameters:
+    - name: id
+      in: path
+      type: number
+      description: id of the conversation
+      required: true
+  responses:
+    204:
+      description: Success
+      schema:
+        $ref: '#/definitions/conversation_status_toggle'
+    404:
+      description: Conversation not found
+    403:
+      description: Access denied

swagger/paths/conversation/update_last_seen.yml

@@ -0,0 +1,17 @@
+post:
+  tags: [Conversation]
+  summary: Update Last Seen
+  description: Updates the last seen of the conversation so that conversations will have the bubbles in the agents screen
+  parameters:
+    - name: id
+      in: path
+      type: number
+      description: id of the conversation
+      required: true
+  responses:
+    200:
+      description: Success
+    404:
+      description: Contact not found
+    403:
+      description: Access denied

swagger/paths/index.yml

@@ -5,3 +5,19 @@
   $ref: ./contact/crud.yml
 /contacts/{id}/conversations:
   $ref: ./contact/conversations.yml
+
+# Conversations
+/conversations:
+  $ref: ./conversation/list.yml
+/conversations/{id}:
+  $ref: ./conversation/crud.yml
+/conversations/{id}/toggle_status:
+  $ref: ./conversation/toggle_status.yml
+/conversations/{id}/update_last_seen:
+  $ref: ./conversation/update_last_seen.yml
+/conversations/{id}/labels:
+  $ref: ./conversation/labels.yml
+/conversations/{id}/assignments:
+  $ref: ./conversation/assignments.yml
+/conversations/{id}/messages:
+  $ref: ./conversation/messages.yml