chore: Add API documentation for teams (chatwoot#2221)

Add API documentation for teams

Gemfile

@@ -112,7 +112,7 @@ group :development do
   gem 'web-console'
 
   # used in swagger build
-  gem 'json_refs', git: 'https://github.com/tzmfreedom/json_refs', ref: 'e32deb0'
+  gem 'json_refs', git: 'https://github.com/tzmfreedom/json_refs', ref: '131b11294fd6af9c428171f38516e6222a58c874'
 
   # When we want to squash migrations
   gem 'squasher'

Gemfile.lock

@@ -7,10 +7,10 @@ GIT
 
 GIT
   remote: https://github.com/tzmfreedom/json_refs
-  revision: e32deb073ce9aef39bdd63556bffd7fe7c2a803d
-  ref: e32deb0
+  revision: 131b11294fd6af9c428171f38516e6222a58c874
+  ref: 131b11294fd6af9c428171f38516e6222a58c874
   specs:
-    json_refs (0.1.2)
+    json_refs (0.1.6)
       hana
 
 GEM
@@ -250,7 +250,7 @@ GEM
       activerecord (>= 5.0, < 7)
       ruby2ruby (~> 2.4)
       ruby_parser (~> 3.10)
-    hana (1.3.6)
+    hana (1.3.7)
     hashdiff (1.0.1)
     hashie (4.1.0)
     hkdf (0.3.0)

swagger/definitions/index.yml

@@ -23,6 +23,8 @@ contact_inboxes:
   $ref: ./resource/contact_inboxes.yml
 account:
   $ref: ./resource/account.yml
+team:
+  $ref: ./resource/team.yml
 
 # RESPONSE
 
@@ -78,3 +80,8 @@ contact_update:
 ## conversation
 conversation_message_create:
   $ref: ./request/conversation/create_message.yml
+
+# Team request Payload
+
+team_create_update_payload:
+  $ref: ./request/team/create_update_payload.yml

swagger/definitions/request/team/create_update_payload.yml

@@ -0,0 +1,11 @@
+type: object
+properties:
+  name:
+    type: string
+    description: The name of the team
+  description:
+    type: string
+    description: The description of the team
+  allow_auto_assign:
+    type: boolean
+    description: If this setting is turned on, the system would automatically assign the conversation to an agent in the team while assigning the conversation to a team

swagger/definitions/resource/team.yml

@@ -0,0 +1,20 @@
+type: object
+properties:
+  id:
+    type: number
+    description: The id of the team
+  name:
+    type: string
+    description: The name of the team
+  description:
+    type: string
+    description: The description about the team
+  allow_auto_assign:
+    type: boolean
+    description: If this setting is turned on, the system would automatically assign the conversation to an agent in the team while assigning the conversation to a team
+  account_id:
+    type: number
+    description: The id of the account with the team is a part of
+  is_member:
+    type: boolean
+    description: This field shows whether the current user is a part of the team

swagger/index.html

@@ -5,14 +5,14 @@
     <!-- needed for adaptive design -->
     <meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
     <!--
     ReDoc doesn't change outer page styles
     -->
     <style>
       body {
         margin: 0;
         padding: 0;
+        font-family:  'Helvetica Neue', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', sans-serif;
       }
     </style>
   </head>

swagger/index.yml

@@ -1,4 +1,4 @@
-swagger: 2.0
+swagger: "2.0"
 info:
   description: This is the API documentation for Chatwoot server.
   version: 1.0.0
@@ -40,3 +40,5 @@ paths:
   $ref: ./paths/index.yml
 definitions:
   $ref: ./definitions/index.yml
+parameters:
+  $ref: ./parameters/index.yml

swagger/parameters/account_id.yml

@@ -0,0 +1,6 @@
+in: path
+name: account_id
+schema:
+  type: integer
+required: true
+description: Numeric ID of the account

swagger/parameters/index.yml

@@ -0,0 +1,5 @@
+account_id:
+  $ref: ./account_id.yml
+
+team_id:
+  $ref: ./team_id.yml

swagger/parameters/team_id.yml

@@ -0,0 +1,6 @@
+in: path
+name: id
+schema:
+  type: integer
+required: true
+description: The id of the team to be updated

swagger/paths/conversation/assignments.yml

@@ -3,7 +3,7 @@ post:
     - ConversationAssignment
   operationId: conversationAssignment
   summary: Assign Conversation
-  description: Assign a conversation to an agent
+  description: Assign a conversation to an agent or a team
   parameters:
     - name: id
       in: path
@@ -18,6 +18,10 @@ post:
         properties:
           assignee_id:
             type: number
+            description: Id of the assignee user
+          team_id:
+            type: number
+            description: Id of the team. If the assignee_id is present, this param would be ignored
   responses:
     200:
       description: Success

swagger/paths/index.yml

@@ -52,3 +52,23 @@
 # Profile
 /profile:
   $ref: ./profile/index.yml
+
+# Teams
+/accounts/{account_id}/teams:
+  parameters:
+    - $ref: '#/parameters/account_id'
+  get:
+    $ref: ./teams/index.yml
+  post:
+    $ref: ./teams/create.yml
+
+/accounts/{account_id}/teams/{id}:
+  parameters:
+    - $ref: '#/parameters/account_id'
+    - $ref: '#/parameters/team_id'
+  get:
+    $ref: './teams/show.yml'
+  patch:
+    $ref: ./teams/update.yml
+  delete:
+    $ref: ./teams/delete.yml

swagger/paths/teams/create.yml

@@ -0,0 +1,19 @@
+tags:
+  - Teams
+operationId: create-a-team
+summary: Create a team
+description: Create a team in the account
+parameters:
+  - $ref: '#/parameters/account_id'
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/team_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/team'
+  401:
+    description: Unauthorized

swagger/paths/teams/delete.yml

@@ -0,0 +1,12 @@
+tags:
+  - Teams
+operationId: delete-a-team,
+summary: Delete a team
+description: Delete a team from the account
+responses:
+  200:
+    description: Success
+  401:
+    description: Unauthorized
+  404:
+    description: The team does not exist in the account

swagger/paths/teams/index.yml

@@ -0,0 +1,14 @@
+tags:
+  - Teams
+operationId: list-all-teams
+summary: List all teams
+description: List all teams available in the current account
+responses:
+  200:
+    description: Success
+    schema:
+      type: array
+      description: 'Array of teams'
+      $ref: '#/definitions/team'
+  401:
+    description: Unauthorized

swagger/paths/teams/show.yml

@@ -0,0 +1,14 @@
+tags:
+  - Teams
+operationId: get-details-of-a-single-team
+summary: Get a team details
+description: Get the details of a team in the account
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/team'
+  401:
+    description: Unauthorized
+  404:
+    description: The given team id does not exist in the account

swagger/paths/teams/update.yml

@@ -0,0 +1,18 @@
+tags:
+  - Teams
+operationId: update-a-team
+summary: Update a team
+description: Update a team's attributes
+parameters:
+  - name: data
+    in: body
+    required: true
+    schema:
+      $ref: '#/definitions/team_create_update_payload'
+responses:
+  200:
+    description: Success
+    schema:
+      $ref: '#/definitions/team'
+  401:
+    description: Unauthorized