chore: Add Swagger docs for Platform APIs (#2349)

2021-05-31 10:58:43 +05:30
parent cc75a668cb
commit 9d16e52e33
37 changed files with 2315 additions and 837 deletions
--- a/swagger/paths/agent_bots/create.yml
+++ b/swagger/paths/agent_bots/create.yml
@@ -0,0 +1,19 @@
+tags:
+  - Account AgentBots
+operationId: create-an-account-agent-bot
+summary: Create an Agent Bot
+description: Create an agent bot in the account
+parameters:
+  - $ref: '#/parameters/account_id'
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/agent_bot_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/agent_bot'
+  401:
+    description: Unauthorized
--- a/swagger/paths/agent_bots/delete.yml
+++ b/swagger/paths/agent_bots/delete.yml
@@ -0,0 +1,12 @@
+tags:
+  - Account AgentBots
+operationId: delete-an-account-agent-bot
+summary: Delete an AgentBot
+description: Delete an AgentBot from the account
+responses:
+  200:
+    description: Success
+  401:
+    description: Unauthorized
+  404:
+    description: The agent bot does not exist in the account
--- a/swagger/paths/agent_bots/index.yml
+++ b/swagger/paths/agent_bots/index.yml
@@ -1,17 +1,16 @@
-get:
-  tags:
-    - AgentBot
-  operationId: listAgentBots
-  summary: List all agentbots
-  description: List all available agentbots for the current installation
-  responses:
-    200:
-      description: Success
-      schema:
-        type: Array
-        description: 'List of agent bots'
-        $ref: '#/definitions/agent_bot'
-    404:
-      description: Inbox not found, Agent bot not found
-    403:
-      description: Access denied
+tags:
+  - Account AgentBots
+operationId: list-all-account-agent-bots
+summary: List all AgentBots
+description: List all agent bots available for the current account
+responses:
+  200:
+    description: Success
+    schema:
+      type: array
+      description: 'Array of agent bots'
+      items:
+        - $ref: '#/definitions/agent_bot'
+
+  401:
+    description: Unauthorized
--- a/swagger/paths/agent_bots/show.yml
+++ b/swagger/paths/agent_bots/show.yml
@@ -0,0 +1,14 @@
+tags:
+  - Account AgentBots
+operationId: get-details-of-a-single-account-agent-bot
+summary: Get an agent bot details
+description: Get the details of an agent bot in the account
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/agent_bot'
+  401:
+    description: Unauthorized
+  404:
+    description: The given agent bot ID does not exist in the account
--- a/swagger/paths/agent_bots/update.yml
+++ b/swagger/paths/agent_bots/update.yml
@@ -0,0 +1,18 @@
+tags:
+  - Account AgentBots
+operationId: update-an-account-agent-bot
+summary: Update an agent bot
+description: Update an agent bot's attributes
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/agent_bot_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/agent_bot'
+  401:
+    description: Unauthorized
--- a/swagger/paths/inboxes/get_agent_bot.yml
+++ b/swagger/paths/inboxes/get_agent_bot.yml
@@ -0,0 +1,21 @@
+get:
+  tags:
+    - Inbox
+  operationId: getInboxAgentBot
+  summary: Show Inbox Agent Bot
+  description: See if an agent bot is associated to the Inbox
+  parameters:
+    - name: id
+      in: path
+      type: number
+      description: ID of the inbox
+      required: true
+  responses:
+    204:
+      description: Success
+      schema:
+        $ref: '#/definitions/agent_bot'
+    404:
+      description: Inbox not found, Agent bot not found
+    403:
+      description: Access denied
--- a/swagger/paths/inboxes/index.yml
+++ b/swagger/paths/inboxes/index.yml
@@ -10,7 +10,8 @@ get:
      schema:
        type: array
        description: 'Array of inboxes'
-        $ref: '#/definitions/inbox'
+        items:
+          $ref: '#/definitions/inbox'
    404:
      description: Inbox not found
    403:
--- a/swagger/paths/index.yml
+++ b/swagger/paths/index.yml
@@ -1,61 +1,138 @@
+# ------------  Platform API routes  ------------#
+
+# Accounts
+
+platform/api/v1/accounts:
+  post:
+    $ref: ./platform/accounts/create.yml
+platform/api/v1/accounts/{id}:
+  parameters:
+    - $ref: '#/parameters/account_id'
+  get:
+    $ref: './platform/accounts/show.yml'
+  patch:
+    $ref: ./platform/accounts/update.yml
+  delete:
+    $ref: ./platform/accounts/delete.yml


+# Account Users

-# Inboxes
-/accounts/{account_id}/inboxes:
-  $ref: ./inboxes/index.yml
-/accounts/{account_id}/inboxes/:
-  $ref: ./inboxes/create.yml
-/accounts/{account_id}/inboxes/{id}:
-  $ref: ./inboxes/update.yml
-/accounts/{account_id}/inboxes/{id}/set_agent_bot:
-  $ref: ./inboxes/set_agent_bot.yml
+platform/api/v1/accounts/{id}/account_users:
+  parameters:
+    - $ref: '#/parameters/account_id'
+  get:
+    $ref: './platform/account_users/index.yml'
+  post:
+    $ref: ./platform/account_users/create.yml
+  delete:
+    $ref: ./platform/account_users/delete.yml
+
+# AgentBots
+
+platform/api/v1/agent_bots:
+  get:
+    $ref: ./platform/agent_bots/index.yml
+  post:
+    $ref: ./platform/agent_bots/create.yml
+platform/api/v1/agent_bots/{id}:
+  parameters:
+    - $ref: '#/parameters/agent_bot_id'
+  get:
+    $ref: './platform/agent_bots/show.yml'
+  patch:
+    $ref: ./platform/agent_bots/update.yml
+  delete:
+    $ref: ./platform/agent_bots/delete.yml
+
+# Users
+
+platform/api/v1/users:
+  post:
+    $ref: ./platform/users/create.yml
+platform/api/v1/users/{id}:
+  parameters:
+    - $ref: '#/parameters/user_id'
+  get:
+    $ref: './platform/users/show.yml'
+  patch:
+    $ref: ./platform/users/update.yml
+  delete:
+    $ref: ./platform/users/delete.yml
+platform/api/v1/users/{id}/login:
+  parameters:
+    - $ref: '#/parameters/user_id'
+  $ref: './platform/users/login.yml'
+
+
+# ---------------- end of platform path -----------#
+
+# AgentBots
+
+/api/v1/accounts/{account_id}/agent_bots:
+  parameters:
+    - $ref: '#/parameters/account_id'
+  get:
+    $ref: ./agent_bots/index.yml
+  post:
+    $ref: ./agent_bots/create.yml
+/api/v1/accounts/{account_id}/agent_bots/{id}:
+  parameters:
+    - $ref: '#/parameters/account_id'
+    - $ref: '#/parameters/agent_bot_id'
+  get:
+    $ref: './agent_bots/show.yml'
+  patch:
+    $ref: ./agent_bots/update.yml
+  delete:
+    $ref: ./agent_bots/delete.yml
+
+
+# Contacts
+/api/v1/accounts/{account_id}/contacts:
+  $ref: ./contact/list_create.yml
+/api/v1/accounts/{account_id}/contacts/{id}:
+  $ref: ./contact/crud.yml
+/api/v1/accounts/{account_id}/contacts/{id}/conversations:
+  $ref: ./contact/conversations.yml
+/api/v1/accounts/{account_id}/contacts/search:
+  $ref: ./contact/search.yml
+/api/v1/accounts/{account_id}/contacts/{id}/contact_inboxes:
+  $ref: ./contact_inboxes/create.yml
+/api/v1/accounts/{account_id}/contacts/{id}/contactable_inboxes:
+  $ref: ./contactable_inboxes/get.yml

-/agent_bots:
-  $ref: ./agent_bots/index.yml

 # Conversations
-/accounts/{account_id}/conversations:
+/api/v1/accounts/{account_id}/conversations:
  parameters:
    - $ref: '#/parameters/account_id'
  $ref: ./conversation/index_or_create.yml
-
-/accounts/{account_id}/conversations/{converstion_id}:
+/api/v1/accounts/{account_id}/conversations/{converstion_id}:
  parameters:
    - $ref: '#/parameters/account_id'
    - $ref: '#/parameters/conversation_id'
  get:
    $ref: ./conversation/show.yml
-
-/accounts/{account_id}/conversations/{conversation_id}/toggle_status:
+/api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_status:
  parameters:
    - $ref: '#/parameters/account_id'
    - $ref: '#/parameters/conversation_id'
  post:
    $ref: ./conversation/toggle_status.yml

-# Messages
-/accounts/{account_id}/conversations/{id}/messages:
-  $ref: ./conversation/messages/create_attachment.yml
-/accounts/{account_id}/conversations/{converstion_id}/messages:
+# Conversations Assignments
+
+/api/v1/accounts/{account_id}/conversations/{conversation_id}/assignments:
  parameters:
    - $ref: '#/parameters/account_id'
    - $ref: '#/parameters/conversation_id'
-  get:
-    $ref: ./conversation/messages/index.yml
  post:
-    $ref: ./conversation/messages/create.yml
+    $ref: ./conversation/assignments.yml

-/accounts/{account_id}/conversations/{conversation_id}/messages/{message_id}:
-  parameters:
-    - $ref: '#/parameters/account_id'
-    - $ref: '#/parameters/conversation_id'
-    - $ref: '#/parameters/message_id'
-  delete:
-    $ref: ./conversation/messages/delete.yml
+# Conversation Labels

-
-/accounts/{account_id}/conversations/{conversation_id}/labels:
+/api/v1/accounts/{account_id}/conversations/{conversation_id}/labels:
  parameters:
    - $ref: '#/parameters/account_id'
    - $ref: '#/parameters/conversation_id'
@@ -64,46 +141,71 @@
  post:
    $ref: ./conversation/labels/create.yml

-/accounts/{account_id}/conversations/{conversation_id}/assignments:
+
+# Inboxes
+/api/v1/accounts/{account_id}/inboxes:
+  $ref: ./inboxes/index.yml
+/api/v1/accounts/{account_id}/inboxes/:
+  $ref: ./inboxes/create.yml
+/api/v1/accounts/{account_id}/inboxes/{id}:
+  $ref: ./inboxes/update.yml
+/api/v1/accounts/{account_id}/inboxes/{id}/agent_bot:
+  $ref: ./inboxes/get_agent_bot.yml
+/api/v1/accounts/{account_id}/inboxes/{id}/set_agent_bot:
+  $ref: ./inboxes/set_agent_bot.yml
+
+
+# Messages
+/api/v1/accounts/{account_id}/conversations/{id}/messages:
+  $ref: ./conversation/messages/create_attachment.yml
+/api/v1/accounts/{account_id}/conversations/{converstion_id}/messages:
  parameters:
    - $ref: '#/parameters/account_id'
    - $ref: '#/parameters/conversation_id'
+  get:
+    $ref: ./conversation/messages/index.yml
  post:
-    $ref: ./conversation/assignments.yml
+    $ref: ./conversation/messages/create.yml
+/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages/{message_id}:
+  parameters:
+    - $ref: '#/parameters/account_id'
+    - $ref: '#/parameters/conversation_id'
+    - $ref: '#/parameters/message_id'
+  delete:
+    $ref: ./conversation/messages/delete.yml

-# Contacts
-/accounts/{account_id}/contacts:
-  $ref: ./contact/list_create.yml

-/accounts/{account_id}/contacts/{id}:
-  $ref: ./contact/crud.yml

-/accounts/{account_id}/contacts/{id}/conversations:
-  $ref: ./contact/conversations.yml
+# Integrations
+/api/v1/accounts/{account_id}/integrations/apps:
+  parameters:
+    - $ref: '#/parameters/account_id'
+  get:
+    $ref: './integrations/apps/show.yml'
+/api/v1/accounts/{account_id}/integrations/hooks:
+  post:
+    $ref: './integrations/hooks/create.yml'
+  patch:
+    $ref: ./integrations/hooks/update.yml
+  delete:
+    $ref: ./integrations/hooks/delete.yml

-/accounts/{account_id}/contacts/search:
-  $ref: ./contact/search.yml
-
-/accounts/{account_id}/contacts/{id}/contact_inboxes:
-  $ref: ./contact_inboxes/create.yml
-/accounts/{account_id}/contacts/{id}/contactable_inboxes:
-  $ref: ./contactable_inboxes/get.yml


 # Profile
 /profile:
  $ref: ./profile/index.yml

+
 # Teams
-/accounts/{account_id}/teams:
+/api/v1/accounts/{account_id}/teams:
  parameters:
    - $ref: '#/parameters/account_id'
  get:
    $ref: ./teams/index.yml
  post:
    $ref: ./teams/create.yml
-
-/accounts/{account_id}/teams/{id}:
+/api/v1/accounts/{account_id}/teams/{id}:
  parameters:
    - $ref: '#/parameters/account_id'
    - $ref: '#/parameters/team_id'
@@ -114,19 +216,3 @@
  delete:
    $ref: ./teams/delete.yml

-
-# Integrations
-/accounts/{account_id}/integrations/apps:
-  parameters:
-    - $ref: '#/parameters/account_id'
-  get:
-    $ref: './integrations/apps/show.yml'
-  
- 
-/accounts/{account_id}/integrations/hooks:
-  post:
-    $ref: './integrations/hooks/create.yml'
-  patch:
-    $ref: ./integrations/hooks/update.yml
-  delete:
-    $ref: ./integrations/hooks/delete.yml
--- a/swagger/paths/integrations/apps/show.yml
+++ b/swagger/paths/integrations/apps/show.yml
@@ -7,7 +7,10 @@ responses:
  200:
    description: Success
    schema:
-      $ref: '#/definitions/integrations_app'
+      type: array
+      description: 'Array of Integration apps'
+      items:
+        $ref: '#/definitions/integrations_app'
  401:
    description: Unauthorized
  404:
--- a/swagger/paths/platform/account_users/create.yml
+++ b/swagger/paths/platform/account_users/create.yml
@@ -0,0 +1,40 @@
+tags:
+  - Account Users
+operationId: create-an-account-user
+summary: Create an Account User
+description: Create an Account User
+security:
+  - platformAppApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      type: object
+      properties: 
+        user_id:
+          type: integer
+          description: The ID of the user
+          required: true
+        role:
+          type: string
+          description: whether user is an administrator or agent
+          required: true
+      
+responses:
+  200:
+    description: Success
+    schema:
+      properties: 
+        account_id:
+          type: integer
+          description: The ID of the user
+        user_id:
+          type: integer
+          description: The ID of the user
+        role:
+          type: string
+          description: whether user is an administrator or agent
+      
+  401:
+    description: Unauthorized
--- a/swagger/paths/platform/account_users/delete.yml
+++ b/swagger/paths/platform/account_users/delete.yml
@@ -0,0 +1,26 @@
+tags:
+  - Account Users
+operationId: delete-an-account-user
+summary: Delete an Account User
+description: Delete an Account User
+security:
+  - platformAppApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      type: object
+      properties: 
+        user_id:
+          type: integer
+          description: The ID of the user
+          required: true
+
+responses:
+  200:
+    description: Success
+  401:
+    description: Unauthorized
+  404:
+    description: The account does not exist
--- a/swagger/paths/platform/account_users/index.yml
+++ b/swagger/paths/platform/account_users/index.yml
@@ -0,0 +1,28 @@
+tags:
+  - Account Users
+operationId: list-all-account-users
+summary: List all Account Users
+description: List all account users
+security:
+  - platformAppApiKey: []
+responses:
+  200:
+    description: Success
+    schema:
+      type: array
+      description: 'Array of account users'
+      items:
+        type: object
+        properties: 
+          account_id:
+            type: integer
+            description: The ID of the user
+          user_id:
+            type: integer
+            description: The ID of the user
+          role:
+            type: string
+            description: whether user is an administrator or agent
+      
+  401:
+    description: Unauthorized
--- a/swagger/paths/platform/accounts/create.yml
+++ b/swagger/paths/platform/accounts/create.yml
@@ -0,0 +1,20 @@
+tags:
+  - Accounts
+operationId: create-an-account
+summary: Create an Account
+description: Create an Account
+security:
+  - platformAppApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/account_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/platform_account'
+  401:
+    description: Unauthorized
--- a/swagger/paths/platform/accounts/delete.yml
+++ b/swagger/paths/platform/accounts/delete.yml
@@ -0,0 +1,14 @@
+tags:
+  - Accounts
+operationId: delete-an-account
+summary: Delete an Account
+description: Delete an Account
+security:
+  - platformAppApiKey: []
+responses:
+  200:
+    description: Success
+  401:
+    description: Unauthorized
+  404:
+    description: The account does not exist
--- a/swagger/paths/platform/accounts/show.yml
+++ b/swagger/paths/platform/accounts/show.yml
@@ -0,0 +1,16 @@
+tags:
+  - Accounts
+operationId: get-details-of-an-account
+summary: Get an account details
+description: Get the details of an account
+security:
+  - platformAppApiKey: []
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/platform_account'
+  401:
+    description: Unauthorized
+  404:
+    description: The given account does not exist
--- a/swagger/paths/platform/accounts/update.yml
+++ b/swagger/paths/platform/accounts/update.yml
@@ -0,0 +1,20 @@
+tags:
+  - Accounts
+operationId: update-an-account
+summary: Update an account
+description: Update an account's attributes
+security:
+  - platformAppApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/account_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/platform_account'
+  401:
+    description: Unauthorized
--- a/swagger/paths/platform/agent_bots/create.yml
+++ b/swagger/paths/platform/agent_bots/create.yml
@@ -0,0 +1,20 @@
+tags:
+  - AgentBots
+operationId: create-an-agent-bot
+summary: Create an Agent Bot
+description: Create an agent bot
+security:
+  - platformAppApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/agent_bot_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/agent_bot'
+  401:
+    description: Unauthorized
--- a/swagger/paths/platform/agent_bots/delete.yml
+++ b/swagger/paths/platform/agent_bots/delete.yml
@@ -0,0 +1,14 @@
+tags:
+  - AgentBots
+operationId: delete-an-agent-bot
+summary: Delete an AgentBot
+description: Delete an AgentBot
+security:
+  - platformAppApiKey: []
+responses:
+  200:
+    description: Success
+  401:
+    description: Unauthorized
+  404:
+    description: The agent bot does not exist
--- a/swagger/paths/platform/agent_bots/index.yml
+++ b/swagger/paths/platform/agent_bots/index.yml
@@ -0,0 +1,17 @@
+tags:
+  - AgentBots
+operationId: list-all-agent-bots
+summary: List all AgentBots
+description: List all agent bots available
+security:
+  - platformAppApiKey: []
+responses:
+  200:
+    description: Success
+    schema:
+      type: array
+      description: 'Array of agent bots'
+      items:
+        $ref: '#/definitions/agent_bot'
+  401:
+    description: Unauthorized
--- a/swagger/paths/platform/agent_bots/show.yml
+++ b/swagger/paths/platform/agent_bots/show.yml
@@ -0,0 +1,16 @@
+tags:
+  - AgentBots
+operationId: get-details-of-a-single-agent-bot
+summary: Get an agent bot details
+description: Get the details of an agent bot
+security:
+  - platformAppApiKey: []
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/agent_bot'
+  401:
+    description: Unauthorized
+  404:
+    description: The given agent bot ID does not exist
--- a/swagger/paths/platform/agent_bots/update.yml
+++ b/swagger/paths/platform/agent_bots/update.yml
@@ -0,0 +1,20 @@
+tags:
+  - AgentBots
+operationId: update-an-agent-bot
+summary: Update an agent bot
+description: Update an agent bot's attributes
+security:
+  - platformAppApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/agent_bot_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/agent_bot'
+  401:
+    description: Unauthorized
--- a/swagger/paths/platform/users/create.yml
+++ b/swagger/paths/platform/users/create.yml
@@ -0,0 +1,20 @@
+tags:
+  - Users
+operationId: create-a-user
+summary: Create a User
+description: Create a User
+security:
+  - platformAppApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/user_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/user'
+  401:
+    description: Unauthorized
--- a/swagger/paths/platform/users/delete.yml
+++ b/swagger/paths/platform/users/delete.yml
@@ -0,0 +1,14 @@
+tags:
+  - Users
+operationId: delete-a-user
+summary: Delete a User
+description: Delete a User
+security:
+  - platformAppApiKey: []
+responses:
+  200:
+    description: Success
+  401:
+    description: Unauthorized
+  404:
+    description: The user does not exist
--- a/swagger/paths/platform/users/login.yml
+++ b/swagger/paths/platform/users/login.yml
@@ -0,0 +1,21 @@
+get:
+  tags:
+    - Users
+  operationId: get-sso-url-of-a-user
+  summary: Get User SSO Link
+  description: Get the sso link of a user
+  security:
+    - platformAppApiKey: []
+  responses:
+    200:
+      description: Success
+      schema:
+        type: object
+        properties:
+          url:
+            type: string
+            description: SSO url to autenticate the user
+    401:
+      description: Unauthorized
+    404:
+      description: The given user does not exist
--- a/swagger/paths/platform/users/show.yml
+++ b/swagger/paths/platform/users/show.yml
@@ -0,0 +1,16 @@
+tags:
+  - Users
+operationId: get-details-of-a-user
+summary: Get an user details
+description: Get the details of an user
+security:
+  - platformAppApiKey: []
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/user'
+  401:
+    description: Unauthorized
+  404:
+    description: The given user does not exist
--- a/swagger/paths/platform/users/update.yml
+++ b/swagger/paths/platform/users/update.yml
@@ -0,0 +1,20 @@
+tags:
+  - Users
+operationId: update-a-user
+summary: Update a user
+description: Update a user's attributes
+security:
+  - platformAppApiKey: []
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/user_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/user'
+  401:
+    description: Unauthorized
--- a/swagger/paths/teams/index.yml
+++ b/swagger/paths/teams/index.yml
@@ -9,6 +9,7 @@ responses:
    schema:
      type: array
      description: 'Array of teams'
-      $ref: '#/definitions/team'
+      items:
+        $ref: '#/definitions/team'
  401:
    description: Unauthorized