From fd0c26cdae10fa6f7fdc67c155bf20c2586723ee Mon Sep 17 00:00:00 2001 From: Pranav Raj S Date: Wed, 5 May 2021 20:39:00 +0530 Subject: [PATCH] chore: Add API documentation for teams (#2221) Add API documentation for teams --- Gemfile | 2 +- Gemfile.lock | 8 +- swagger/definitions/index.yml | 7 + .../request/team/create_update_payload.yml | 11 + swagger/definitions/resource/team.yml | 20 ++ swagger/index.html | 2 +- swagger/index.yml | 4 +- swagger/parameters/account_id.yml | 6 + swagger/parameters/index.yml | 5 + swagger/parameters/team_id.yml | 6 + swagger/paths/conversation/assignments.yml | 6 +- swagger/paths/index.yml | 20 ++ swagger/paths/teams/create.yml | 19 ++ swagger/paths/teams/delete.yml | 12 + swagger/paths/teams/index.yml | 14 ++ swagger/paths/teams/show.yml | 14 ++ swagger/paths/teams/update.yml | 18 ++ swagger/swagger.json | 215 +++++++++++++++++- 18 files changed, 378 insertions(+), 11 deletions(-) create mode 100644 swagger/definitions/request/team/create_update_payload.yml create mode 100644 swagger/definitions/resource/team.yml create mode 100644 swagger/parameters/account_id.yml create mode 100644 swagger/parameters/index.yml create mode 100644 swagger/parameters/team_id.yml create mode 100644 swagger/paths/teams/create.yml create mode 100644 swagger/paths/teams/delete.yml create mode 100644 swagger/paths/teams/index.yml create mode 100644 swagger/paths/teams/show.yml create mode 100644 swagger/paths/teams/update.yml diff --git a/Gemfile b/Gemfile index d1c6c6534..b8d6d5626 100644 --- a/Gemfile +++ b/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' diff --git a/Gemfile.lock b/Gemfile.lock index 13ac97f9a..4c9b1c465 100644 --- a/Gemfile.lock +++ b/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) diff --git a/swagger/definitions/index.yml b/swagger/definitions/index.yml index 9e09d3332..7f6546a89 100644 --- a/swagger/definitions/index.yml +++ b/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 diff --git a/swagger/definitions/request/team/create_update_payload.yml b/swagger/definitions/request/team/create_update_payload.yml new file mode 100644 index 000000000..f4db1e5d7 --- /dev/null +++ b/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 diff --git a/swagger/definitions/resource/team.yml b/swagger/definitions/resource/team.yml new file mode 100644 index 000000000..ad74be943 --- /dev/null +++ b/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 diff --git a/swagger/index.html b/swagger/index.html index 65ec1b81a..eb09d7768 100644 --- a/swagger/index.html +++ b/swagger/index.html @@ -5,7 +5,6 @@ - @@ -13,6 +12,7 @@ body { margin: 0; padding: 0; + font-family: 'Helvetica Neue', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', sans-serif; } diff --git a/swagger/index.yml b/swagger/index.yml index b00c78da7..dc9cbedb9 100644 --- a/swagger/index.yml +++ b/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 diff --git a/swagger/parameters/account_id.yml b/swagger/parameters/account_id.yml new file mode 100644 index 000000000..ce2fc68f6 --- /dev/null +++ b/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 diff --git a/swagger/parameters/index.yml b/swagger/parameters/index.yml new file mode 100644 index 000000000..d4f901ea2 --- /dev/null +++ b/swagger/parameters/index.yml @@ -0,0 +1,5 @@ +account_id: + $ref: ./account_id.yml + +team_id: + $ref: ./team_id.yml diff --git a/swagger/parameters/team_id.yml b/swagger/parameters/team_id.yml new file mode 100644 index 000000000..096656d2a --- /dev/null +++ b/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 diff --git a/swagger/paths/conversation/assignments.yml b/swagger/paths/conversation/assignments.yml index 7edfb0b48..14788d02a 100644 --- a/swagger/paths/conversation/assignments.yml +++ b/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 diff --git a/swagger/paths/index.yml b/swagger/paths/index.yml index d31f88e4a..f2fa08a0f 100644 --- a/swagger/paths/index.yml +++ b/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 diff --git a/swagger/paths/teams/create.yml b/swagger/paths/teams/create.yml new file mode 100644 index 000000000..2ec066738 --- /dev/null +++ b/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 diff --git a/swagger/paths/teams/delete.yml b/swagger/paths/teams/delete.yml new file mode 100644 index 000000000..264a4ef92 --- /dev/null +++ b/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 diff --git a/swagger/paths/teams/index.yml b/swagger/paths/teams/index.yml new file mode 100644 index 000000000..8e1384cf9 --- /dev/null +++ b/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 diff --git a/swagger/paths/teams/show.yml b/swagger/paths/teams/show.yml new file mode 100644 index 000000000..d7ccdbb04 --- /dev/null +++ b/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 diff --git a/swagger/paths/teams/update.yml b/swagger/paths/teams/update.yml new file mode 100644 index 000000000..8afeddc02 --- /dev/null +++ b/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 diff --git a/swagger/swagger.json b/swagger/swagger.json index 1fe6583a8..4543e1fa1 100644 --- a/swagger/swagger.json +++ b/swagger/swagger.json @@ -1,5 +1,5 @@ { - "swagger": 2.0, + "swagger": "2.0", "info": { "description": "This is the API documentation for Chatwoot server.", "version": "1.0.0", @@ -698,7 +698,7 @@ ], "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", @@ -715,7 +715,12 @@ "type": "object", "properties": { "assignee_id": { - "type": "number" + "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" } } } @@ -1002,6 +1007,144 @@ } } } + }, + "/accounts/{account_id}/teams": { + "parameters": [ + { + "$ref": "#/parameters/account_id" + } + ], + "get": { + "tags": [ + "Teams" + ], + "operationId": "list-all-teams", + "summary": "List all teams", + "description": "List all teams available in the current account", + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/team" + } + }, + "401": { + "description": "Unauthorized" + } + } + }, + "post": { + "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" + } + } + } + }, + "/accounts/{account_id}/teams/{id}": { + "parameters": [ + { + "$ref": "#/parameters/account_id" + }, + { + "$ref": "#/parameters/team_id" + } + ], + "get": { + "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" + } + } + }, + "patch": { + "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" + } + } + }, + "delete": { + "tags": [ + "Teams" + ], + "operationId": "delete-a-tea,", + "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" + } + } + } } }, "definitions": { @@ -1326,6 +1469,35 @@ } } }, + "team": { + "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" + } + } + }, "extended_contact": { "allOf": [ { @@ -1671,6 +1843,43 @@ "description": "attributes based on your content type" } } + }, + "team_create_update_payload": { + "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" + } + } + } + }, + "parameters": { + "account_id": { + "in": "path", + "name": "account_id", + "schema": { + "type": "integer" + }, + "required": true, + "description": "Numeric ID of the account" + }, + "team_id": { + "in": "path", + "name": "id", + "schema": { + "type": "integer" + }, + "required": true, + "description": "The id of the team to be updated" } } } \ No newline at end of file