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/definitions/index.yml

@@ -5,35 +5,68 @@ request_error:
   $ref: ./error/request.yml
 
 # RESOURCE
+generic_id:
+  $ref: ./resource/extension/generic.yml
 contact:
   $ref: ./resource/contact.yml
 conversation:
   $ref: ./resource/conversation.yml
+message:
+  $ref: ./resource/message.yml
+user:
+  $ref: ./resource/user.yml
 
 # RESPONSE
+
+## contact
 extended_contact:
   allOf:
     - $ref: '#/definitions/contact'
     - $ref: ./resource/extension/contact/show.yml
 contact_base:
   allOf:
+    - $ref: '#/definitions/generic_id'
     - $ref: '#/definitions/contact'
-    - $ref: ./resource/extension/generic.yml
 contact_list:
   type: array
+  description: 'array of contacts'
   items:
     allOf:
+      - $ref: '#/definitions/generic_id'
       - $ref: '#/definitions/contact'
-      - $ref: ./resource/extension/generic.yml
 contact_conversations:
   type: array
+  description: 'array of conversations'
   items:
     allOf:
       - $ref: '#/definitions/conversation'
       - $ref: ./resource/extension/contact/conversation.yml
+      - $ref: ./resource/extension/conversation/with_display_id.yml
+
+## conversation
+conversation_list:
+  $ref: ./resource/extension/conversation/list.yml
+conversation_show:
+  $ref: ./resource/extension/conversation/show.yml
+conversation_status_toggle:
+  $ref: ./resource/extension/conversation/status_toggle.yml
+conversation_labels:
+  $ref: ./resource/extension/conversation/labels.yml
+
+## message
+extended_message:
+  allOf:
+    - $ref: '#/definitions/generic_id'
+    - $ref: '#/definitions/message'
+    - $ref: ./resource/extension/message/with_source_sender.yml
 
 # REQUEST
+
+## contact
 contact_create:
   $ref: ./request/contact/create.yml
 contact_update:
   $ref: ./request/contact/update.yml
+## conversation
+conversation_message_create:
+  $ref: ./request/conversation/create_message.yml

swagger/definitions/request/conversation/create_message.yml

@@ -0,0 +1,10 @@
+type: object
+properties:
+  conversation_id:
+    type: number
+  message:
+    type: string
+  private:
+    type: boolean
+  fb_id:
+    type: number

swagger/definitions/resource/conversation.yml

@@ -1,7 +1,5 @@
 type: object
 properties:
-  display_id:
-    type: number
   messages:
     type: array
     items:

swagger/definitions/resource/extension/contact/conversation.yml

@@ -15,4 +15,4 @@ properties:
           channel:
             type: string
       assignee:
-        type: object
+        $ref: '#/definitions/user'

swagger/definitions/resource/extension/contact/list.yml

@@ -1,5 +0,0 @@
-type: object
-properties:
-  allOf:
-    - $ref: '#/definitions/contact'
-    - $ref: ./resource/extension/contact.yaml

swagger/definitions/resource/extension/conversation/labels.yml

@@ -0,0 +1,7 @@
+type: object
+properties:
+  payload:
+    type: array
+    description: 'array of labels'
+    items:
+      type: string

swagger/definitions/resource/extension/conversation/list.yml

@@ -0,0 +1,22 @@
+type: object
+properties:
+  data:
+    type: object
+    properties:
+      meta:
+        type: object
+        properties:
+          mine_count:
+            type: number
+          unassigned_count:
+            type: number
+          all_count:
+            type: number
+      payload:
+        type: array
+        description: 'array of conversations'
+        items:
+          allOf:
+            - $ref: '#/definitions/generic_id'
+            - $ref: '#/definitions/conversation'
+            - $ref: '../contact/conversation.yml'

swagger/definitions/resource/extension/conversation/show.yml

@@ -0,0 +1,19 @@
+type: object
+properties:
+  meta:
+    type: object
+    properties:
+      labels:
+        type: array
+        items:
+          type: string
+      additional_attributes:
+        type: object
+      contact_id:
+        type: number
+  payload:
+    type: array
+    description: 'array of messages'
+    items:
+      allOf:
+        - $ref: '#/definitions/extended_message'

swagger/definitions/resource/extension/conversation/status_toggle.yml

@@ -0,0 +1,14 @@
+type: object
+properties:
+  meta:
+    type: object
+  payload:
+    type: object
+    properties:
+      success:
+        type: boolean
+      current_status:
+        type: string
+        enum: ['open', 'resolved']
+      conversation_id:
+        type: number

swagger/definitions/resource/extension/conversation/with_display_id.yml

@@ -0,0 +1,4 @@
+type: object
+properties:
+  display_id:
+    type: number

swagger/definitions/resource/extension/message/with_source_sender.yml

@@ -0,0 +1,6 @@
+type: object
+properties:
+  source_id:
+    type: number
+  sender:
+    type: object

swagger/definitions/resource/message.yml

@@ -0,0 +1,16 @@
+type: object
+properties:
+  content:
+    type: string
+  inbox_id:
+    type: number
+  conversation_id:
+    type: number
+  message_type:
+    type: string
+  created_at:
+    type: integer
+  private:
+    type: boolean
+  attachment:
+    type: object

swagger/definitions/resource/user.yml

@@ -0,0 +1,19 @@
+type: object
+properties:
+  id:
+    type: number
+  uid:
+    type: string
+  name:
+    type: string
+  email:
+    type: string
+  account_id:
+    type: number
+  role:
+    type: string
+    enum: ['agent', 'administrator']
+  confirmed:
+    type: boolean
+  nickname:
+    type: string