From 46356d0bf9d2547d66eb7845917cc132ec01fead Mon Sep 17 00:00:00 2001 From: Sojan Jose Date: Thu, 20 May 2021 20:46:45 +0530 Subject: [PATCH] docs: Add documentation for integration APIs (#2300) --- app/views/api/v1/models/_app.json.jbuilder | 6 +- app/views/api/v1/models/_hook.json.jbuilder | 7 +- .../integrations/hooks_controller_spec.rb | 4 +- swagger/definitions/index.yml | 10 + .../integrations/hook_create_payload.yml | 11 + .../integrations/hook_update_payload.yml | 5 + .../definitions/resource/integrations/app.yml | 23 ++ .../resource/integrations/hook.yml | 23 ++ swagger/definitions/resource/team.yml | 4 +- swagger/parameters/hook_id.yml | 6 + swagger/parameters/index.yml | 3 + swagger/parameters/team_id.yml | 2 +- swagger/paths/contact/conversations.yml | 2 +- swagger/paths/contact/crud.yml | 4 +- swagger/paths/contact_inboxes/create.yml | 2 +- .../paths/conversation/update_last_seen.yml | 2 +- swagger/paths/index.yml | 17 ++ swagger/paths/integrations/apps/show.yml | 14 + swagger/paths/integrations/hooks/create.yml | 19 ++ swagger/paths/integrations/hooks/delete.yml | 15 ++ swagger/paths/integrations/hooks/update.yml | 20 ++ swagger/paths/teams/show.yml | 2 +- swagger/swagger.json | 242 +++++++++++++++++- 23 files changed, 421 insertions(+), 22 deletions(-) create mode 100644 swagger/definitions/request/integrations/hook_create_payload.yml create mode 100644 swagger/definitions/request/integrations/hook_update_payload.yml create mode 100644 swagger/definitions/resource/integrations/app.yml create mode 100644 swagger/definitions/resource/integrations/hook.yml create mode 100644 swagger/parameters/hook_id.yml create mode 100644 swagger/paths/integrations/apps/show.yml create mode 100644 swagger/paths/integrations/hooks/create.yml create mode 100644 swagger/paths/integrations/hooks/delete.yml create mode 100644 swagger/paths/integrations/hooks/update.yml diff --git a/app/views/api/v1/models/_app.json.jbuilder b/app/views/api/v1/models/_app.json.jbuilder index 6fce9fee2..33a2bfc88 100644 --- a/app/views/api/v1/models/_app.json.jbuilder +++ b/app/views/api/v1/models/_app.json.jbuilder @@ -3,4 +3,8 @@ json.name resource.name json.description resource.description json.enabled resource.enabled?(@current_account) json.button resource.action -json.hooks @current_account.hooks.where(app_id: resource.id) +json.hooks do + json.array! @current_account.hooks.where(app_id: resource.id) do |hook| + json.partial! 'api/v1/models/hook.json.jbuilder', resource: hook + end +end diff --git a/app/views/api/v1/models/_hook.json.jbuilder b/app/views/api/v1/models/_hook.json.jbuilder index d9860b8a2..e9c921516 100644 --- a/app/views/api/v1/models/_hook.json.jbuilder +++ b/app/views/api/v1/models/_hook.json.jbuilder @@ -1,4 +1,7 @@ json.id resource.id -json.app resource.app.params.to_h -json.enabled resource.enabled? +json.app_id resource.app_id +json.status resource.enabled? json.inbox_id resource.inbox_id +json.account_id resource.account_id +json.hook_type resource.hook_type +json.settings resource.settings diff --git a/spec/controllers/api/v1/accounts/integrations/hooks_controller_spec.rb b/spec/controllers/api/v1/accounts/integrations/hooks_controller_spec.rb index 3c92f9026..63c31d98a 100644 --- a/spec/controllers/api/v1/accounts/integrations/hooks_controller_spec.rb +++ b/spec/controllers/api/v1/accounts/integrations/hooks_controller_spec.rb @@ -36,7 +36,7 @@ RSpec.describe 'Integration Hooks API', type: :request do expect(response).to have_http_status(:success) data = JSON.parse(response.body) - expect(data['app']['id']).to eq params[:app_id] + expect(data['app_id']).to eq params[:app_id] end end end @@ -72,7 +72,7 @@ RSpec.describe 'Integration Hooks API', type: :request do expect(response).to have_http_status(:success) data = JSON.parse(response.body) - expect(data['app']['id']).to eq 'slack' + expect(data['app_id']).to eq 'slack' end end end diff --git a/swagger/definitions/index.yml b/swagger/definitions/index.yml index e72c1743d..7317ff2b0 100644 --- a/swagger/definitions/index.yml +++ b/swagger/definitions/index.yml @@ -27,6 +27,10 @@ account: $ref: ./resource/account.yml team: $ref: ./resource/team.yml +integrations_app: + $ref: ./resource/integrations/app.yml +integrations_hook: + $ref: ./resource/integrations/hook.yml # RESPONSE @@ -87,3 +91,9 @@ conversation_message_create: team_create_update_payload: $ref: ./request/team/create_update_payload.yml + +integrations_hook_create_payload: + $ref: ./request/integrations/hook_create_payload.yml + +integrations_hook_update_payload: + $ref: ./request/integrations/hook_update_payload.yml \ No newline at end of file diff --git a/swagger/definitions/request/integrations/hook_create_payload.yml b/swagger/definitions/request/integrations/hook_create_payload.yml new file mode 100644 index 000000000..d1bf518d8 --- /dev/null +++ b/swagger/definitions/request/integrations/hook_create_payload.yml @@ -0,0 +1,11 @@ +type: object +properties: + app_id: + type: string + description: The ID of app for which integration hook is being created + inbox_id: + type: string + description: The inbox ID, if the hook is an inbox hook + settings: + type: object + description: The settings required by the integration diff --git a/swagger/definitions/request/integrations/hook_update_payload.yml b/swagger/definitions/request/integrations/hook_update_payload.yml new file mode 100644 index 000000000..5b91024db --- /dev/null +++ b/swagger/definitions/request/integrations/hook_update_payload.yml @@ -0,0 +1,5 @@ +type: object +properties: + settings: + type: object + description: The settings required by the integration diff --git a/swagger/definitions/resource/integrations/app.yml b/swagger/definitions/resource/integrations/app.yml new file mode 100644 index 000000000..ce7fb1e75 --- /dev/null +++ b/swagger/definitions/resource/integrations/app.yml @@ -0,0 +1,23 @@ +type: object +properties: + id: + type: string + description: The ID of the integration + name: + type: string + description: The name of the integration + description: + type: string + description: The description about the team + hook_type: + type: string + description: Whether the integration is an account or inbox integration + enabled: + type: boolean + description: Whether the integration is enabled for the account + allow_multiple_hooks: + type: boolean + description: Whether multiple hooks can be created for the integration + hooks: + type: array + description: If there are any hooks created for this integration diff --git a/swagger/definitions/resource/integrations/hook.yml b/swagger/definitions/resource/integrations/hook.yml new file mode 100644 index 000000000..197c8d858 --- /dev/null +++ b/swagger/definitions/resource/integrations/hook.yml @@ -0,0 +1,23 @@ +type: object +properties: + id: + type: string + description: The ID of the integration hook + app_id: + type: string + description: The ID of the integration app + inbox_id: + type: string + description: Inbox ID if its an Inbox integration + account_id: + type: string + description: Account ID of the integration + status: + type: boolean + description: Whether the integration hook is enabled for the account + hook_type: + type: boolean + description: Whether its an account or inbox integration hook + settings: + type: object + description: The associated settings for the integration \ No newline at end of file diff --git a/swagger/definitions/resource/team.yml b/swagger/definitions/resource/team.yml index ad74be943..eda41ed3e 100644 --- a/swagger/definitions/resource/team.yml +++ b/swagger/definitions/resource/team.yml @@ -2,7 +2,7 @@ type: object properties: id: type: number - description: The id of the team + description: The ID of the team name: type: string description: The name of the team @@ -14,7 +14,7 @@ properties: 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 + 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/parameters/hook_id.yml b/swagger/parameters/hook_id.yml new file mode 100644 index 000000000..f1c50c3d4 --- /dev/null +++ b/swagger/parameters/hook_id.yml @@ -0,0 +1,6 @@ +in: path +name: hook_id +schema: + type: integer +required: true +description: The numeric ID of the integration hook diff --git a/swagger/parameters/index.yml b/swagger/parameters/index.yml index 6acf0f37d..ac9c9a37b 100644 --- a/swagger/parameters/index.yml +++ b/swagger/parameters/index.yml @@ -4,6 +4,9 @@ account_id: team_id: $ref: ./team_id.yml +hook_id: + $ref: ./hook_id.yml + source_id: $ref: ./source_id.yml diff --git a/swagger/parameters/team_id.yml b/swagger/parameters/team_id.yml index 096656d2a..e71d32d6e 100644 --- a/swagger/parameters/team_id.yml +++ b/swagger/parameters/team_id.yml @@ -3,4 +3,4 @@ name: id schema: type: integer required: true -description: The id of the team to be updated +description: The ID of the team to be updated diff --git a/swagger/paths/contact/conversations.yml b/swagger/paths/contact/conversations.yml index 525ef56d6..83ef815e3 100644 --- a/swagger/paths/contact/conversations.yml +++ b/swagger/paths/contact/conversations.yml @@ -7,7 +7,7 @@ get: - name: id in: path type: number - description: id of the contact + description: ID of the contact required: true responses: 200: diff --git a/swagger/paths/contact/crud.yml b/swagger/paths/contact/crud.yml index eee353a74..09f02d886 100644 --- a/swagger/paths/contact/crud.yml +++ b/swagger/paths/contact/crud.yml @@ -7,7 +7,7 @@ get: - name: id in: path type: number - description: id of the contact + description: ID of the contact required: true responses: 200: @@ -28,7 +28,7 @@ put: - name: id in: path type: number - description: id of the contact + description: ID of the contact required: true - name: data in: body diff --git a/swagger/paths/contact_inboxes/create.yml b/swagger/paths/contact_inboxes/create.yml index a0f641867..a8069b4b6 100644 --- a/swagger/paths/contact_inboxes/create.yml +++ b/swagger/paths/contact_inboxes/create.yml @@ -13,7 +13,7 @@ post: properties: inbox_id: type: number - description: The id of the inbox + description: The ID of the inbox required: true source_id: $ref: '#/parameters/source_id' diff --git a/swagger/paths/conversation/update_last_seen.yml b/swagger/paths/conversation/update_last_seen.yml index ee5a9bf14..2f26df879 100644 --- a/swagger/paths/conversation/update_last_seen.yml +++ b/swagger/paths/conversation/update_last_seen.yml @@ -8,7 +8,7 @@ post: - name: id in: path type: number - description: id of the conversation + description: ID of the conversation required: true responses: 200: diff --git a/swagger/paths/index.yml b/swagger/paths/index.yml index b47d6cb9c..c8fd3be03 100644 --- a/swagger/paths/index.yml +++ b/swagger/paths/index.yml @@ -113,3 +113,20 @@ $ref: ./teams/update.yml 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 \ No newline at end of file diff --git a/swagger/paths/integrations/apps/show.yml b/swagger/paths/integrations/apps/show.yml new file mode 100644 index 000000000..6d5f8332f --- /dev/null +++ b/swagger/paths/integrations/apps/show.yml @@ -0,0 +1,14 @@ +tags: + - Integrations +operationId: get-details-of-all-integrations +summary: List all the Integrations +description: Get the details of all Integrations available for the account +responses: + 200: + description: Success + schema: + $ref: '#/definitions/integrations_app' + 401: + description: Unauthorized + 404: + description: Url not found diff --git a/swagger/paths/integrations/hooks/create.yml b/swagger/paths/integrations/hooks/create.yml new file mode 100644 index 000000000..42bcb002e --- /dev/null +++ b/swagger/paths/integrations/hooks/create.yml @@ -0,0 +1,19 @@ +tags: + - Integrations +operationId: create-an-integration-hook +summary: Create an integration hook +description: Create an integration hook +parameters: + - $ref: '#/parameters/account_id' + - name: data + in: body + required: true + schema: + $ref: '#/definitions/integrations_hook_create_payload' +responses: + 200: + description: Success + schema: + $ref: '#/definitions/integrations_hook' + 401: + description: Unauthorized diff --git a/swagger/paths/integrations/hooks/delete.yml b/swagger/paths/integrations/hooks/delete.yml new file mode 100644 index 000000000..3e616613b --- /dev/null +++ b/swagger/paths/integrations/hooks/delete.yml @@ -0,0 +1,15 @@ +tags: + - Integrations +operationId: delete-an-integration-hook +summary: Delete an Integration Hook +description: Delete an Integration Hook +parameters: + - $ref: '#/parameters/account_id' + - $ref: '#/parameters/hook_id' +responses: + 200: + description: Success + 401: + description: Unauthorized + 404: + description: The hook does not exist in the account diff --git a/swagger/paths/integrations/hooks/update.yml b/swagger/paths/integrations/hooks/update.yml new file mode 100644 index 000000000..2cfd6877a --- /dev/null +++ b/swagger/paths/integrations/hooks/update.yml @@ -0,0 +1,20 @@ +tags: + - Integrations +operationId: update-an-integrations-hook +summary: Update an Integration Hook +description: Update an Integration Hook +parameters: + - $ref: '#/parameters/account_id' + - $ref: '#/parameters/hook_id' + - name: data + in: body + required: true + schema: + $ref: '#/definitions/integrations_hook_update_payload' +responses: + 200: + description: Success + schema: + $ref: '#/definitions/integrations_hook' + 401: + description: Unauthorized diff --git a/swagger/paths/teams/show.yml b/swagger/paths/teams/show.yml index d7ccdbb04..485b4730b 100644 --- a/swagger/paths/teams/show.yml +++ b/swagger/paths/teams/show.yml @@ -11,4 +11,4 @@ responses: 401: description: Unauthorized 404: - description: The given team id does not exist in the account + description: The given team ID does not exist in the account diff --git a/swagger/swagger.json b/swagger/swagger.json index 2007a76cc..ff823ed84 100644 --- a/swagger/swagger.json +++ b/swagger/swagger.json @@ -957,7 +957,7 @@ "name": "id", "in": "path", "type": "number", - "description": "id of the contact", + "description": "ID of the contact", "required": true } ], @@ -987,7 +987,7 @@ "name": "id", "in": "path", "type": "number", - "description": "id of the contact", + "description": "ID of the contact", "required": true }, { @@ -1027,7 +1027,7 @@ "name": "id", "in": "path", "type": "number", - "description": "id of the contact", + "description": "ID of the contact", "required": true } ], @@ -1107,7 +1107,7 @@ "properties": { "inbox_id": { "type": "number", - "description": "The id of the inbox", + "description": "The ID of the inbox", "required": true }, "source_id": { @@ -1269,7 +1269,7 @@ "description": "Unauthorized" }, "404": { - "description": "The given team id does not exist in the account" + "description": "The given team ID does not exist in the account" } } }, @@ -1321,6 +1321,131 @@ } } } + }, + "/accounts/{account_id}/integrations/apps": { + "parameters": [ + { + "$ref": "#/parameters/account_id" + } + ], + "get": { + "tags": [ + "Integrations" + ], + "operationId": "get-details-of-all-integrations", + "summary": "List all the Integrations", + "description": "Get the details of all Integrations available for the account", + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/integrations_app" + } + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "Url not found" + } + } + } + }, + "/accounts/{account_id}/integrations/hooks": { + "post": { + "tags": [ + "Integrations" + ], + "operationId": "create-an-integration-hook", + "summary": "Create an integration hook", + "description": "Create an integration hook", + "parameters": [ + { + "$ref": "#/parameters/account_id" + }, + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/integrations_hook_create_payload" + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/integrations_hook" + } + }, + "401": { + "description": "Unauthorized" + } + } + }, + "patch": { + "tags": [ + "Integrations" + ], + "operationId": "update-an-integrations-hook", + "summary": "Update an Integration Hook", + "description": "Update an Integration Hook", + "parameters": [ + { + "$ref": "#/parameters/account_id" + }, + { + "$ref": "#/parameters/hook_id" + }, + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/integrations_hook_update_payload" + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/integrations_hook" + } + }, + "401": { + "description": "Unauthorized" + } + } + }, + "delete": { + "tags": [ + "Integrations" + ], + "operationId": "delete-an-integration-hook", + "summary": "Delete an Integration Hook", + "description": "Delete an Integration Hook", + "parameters": [ + { + "$ref": "#/parameters/account_id" + }, + { + "$ref": "#/parameters/hook_id" + } + ], + "responses": { + "200": { + "description": "Success" + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "The hook does not exist in the account" + } + } + } } }, "definitions": { @@ -1662,7 +1787,7 @@ "properties": { "id": { "type": "number", - "description": "The id of the team" + "description": "The ID of the team" }, "name": { "type": "string", @@ -1678,7 +1803,7 @@ }, "account_id": { "type": "number", - "description": "The id of the account with the team is a part of" + "description": "The ID of the account with the team is a part of" }, "is_member": { "type": "boolean", @@ -1686,6 +1811,72 @@ } } }, + "integrations_app": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of the integration" + }, + "name": { + "type": "string", + "description": "The name of the integration" + }, + "description": { + "type": "string", + "description": "The description about the team" + }, + "hook_type": { + "type": "string", + "description": "Whether the integration is an account or inbox integration" + }, + "enabled": { + "type": "boolean", + "description": "Whether the integration is enabled for the account" + }, + "allow_multiple_hooks": { + "type": "boolean", + "description": "Whether multiple hooks can be created for the integration" + }, + "hooks": { + "type": "array", + "description": "If there are any hooks created for this integration" + } + } + }, + "integrations_hook": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The ID of the integration hook" + }, + "app_id": { + "type": "string", + "description": "The ID of the integration app" + }, + "inbox_id": { + "type": "string", + "description": "Inbox ID if its an Inbox integration" + }, + "account_id": { + "type": "string", + "description": "Account ID of the integration" + }, + "status": { + "type": "boolean", + "description": "Whether the integration hook is enabled for the account" + }, + "hook_type": { + "type": "boolean", + "description": "Whether its an account or inbox integration hook" + }, + "settings": { + "type": "object", + "description": "The associated settings for the integration" + } + } + }, "extended_contact": { "allOf": [ { @@ -2048,6 +2239,32 @@ "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" } } + }, + "integrations_hook_create_payload": { + "type": "object", + "properties": { + "app_id": { + "type": "string", + "description": "The ID of app for which integration hook is being created" + }, + "inbox_id": { + "type": "string", + "description": "The inbox ID, if the hook is an inbox hook" + }, + "settings": { + "type": "object", + "description": "The settings required by the integration" + } + } + }, + "integrations_hook_update_payload": { + "type": "object", + "properties": { + "settings": { + "type": "object", + "description": "The settings required by the integration" + } + } } }, "parameters": { @@ -2067,7 +2284,16 @@ "type": "integer" }, "required": true, - "description": "The id of the team to be updated" + "description": "The ID of the team to be updated" + }, + "hook_id": { + "in": "path", + "name": "hook_id", + "schema": { + "type": "integer" + }, + "required": true, + "description": "The numeric ID of the integration hook" }, "source_id": { "type": "string",