From dfb56f6bb8ecec578cefae06d718331359d073de Mon Sep 17 00:00:00 2001 From: Muhsin Keloth Date: Thu, 7 Apr 2022 19:01:31 +0530 Subject: [PATCH] doc: Swagger for custom attribute APIs (#4382) --- swagger/definitions/index.yml | 8 +- .../create_update_payload.yml | 22 ++ .../definitions/resource/custom_attribute.yml | 29 ++ swagger/index.yml | 1 + .../application/custom_attributes/create.yml | 20 ++ .../application/custom_attributes/delete.yml | 20 ++ .../application/custom_attributes/index.yml | 24 ++ .../application/custom_attributes/show.yml | 14 + .../application/custom_attributes/update.yml | 28 ++ swagger/paths/index.yml | 18 ++ swagger/swagger.json | 272 +++++++++++++++++- 11 files changed, 453 insertions(+), 3 deletions(-) create mode 100644 swagger/definitions/request/custom_attribute/create_update_payload.yml create mode 100644 swagger/definitions/resource/custom_attribute.yml create mode 100644 swagger/paths/application/custom_attributes/create.yml create mode 100644 swagger/paths/application/custom_attributes/delete.yml create mode 100644 swagger/paths/application/custom_attributes/index.yml create mode 100644 swagger/paths/application/custom_attributes/show.yml create mode 100644 swagger/paths/application/custom_attributes/update.yml diff --git a/swagger/definitions/index.yml b/swagger/definitions/index.yml index c120320c8..c06dd1471 100644 --- a/swagger/definitions/index.yml +++ b/swagger/definitions/index.yml @@ -14,6 +14,8 @@ generic_id: $ref: ./resource/extension/generic.yml canned_response: $ref: ./resource/canned_response.yml +custom_attribute: + $ref: ./resource/custom_attribute.yml contact: $ref: ./resource/contact.yml conversation: @@ -69,6 +71,8 @@ user_create_update_payload: canned_response_create_update_payload: $ref: ./request/canned_response/create_update_payload.yml +custom_attribute_create_update_payload: + $ref: ./request/custom_attribute/create_update_payload.yml ## contact contact_create: $ref: ./request/contact/create.yml @@ -154,6 +158,6 @@ account_summary: $ref: './resource/reports/summary.yml' agent_conversation_metrics: $ref: './resource/reports/conversation/agent.yml' - - + + diff --git a/swagger/definitions/request/custom_attribute/create_update_payload.yml b/swagger/definitions/request/custom_attribute/create_update_payload.yml new file mode 100644 index 000000000..fd368f98c --- /dev/null +++ b/swagger/definitions/request/custom_attribute/create_update_payload.yml @@ -0,0 +1,22 @@ +type: object +properties: + attribute_display_name: + type: string + description: Attribute display name + attribute_display_type: + type: integer + description: Attribute display type (text- 0, number- 1, currency- 2, percent- 3, link- 4, date- 5, list- 6, checkbox- 7) + attribute_description: + type: string + description: Attribute description + attribute_key: + type: string + description: Attribute unique key value + attribute_values: + type: array + description: Attribute values + items: + type: string + attribute_model: + type: integer + description: Attribute type(conversation_attribute- 0, contact_attribute- 1) diff --git a/swagger/definitions/resource/custom_attribute.yml b/swagger/definitions/resource/custom_attribute.yml new file mode 100644 index 000000000..ba36fd714 --- /dev/null +++ b/swagger/definitions/resource/custom_attribute.yml @@ -0,0 +1,29 @@ +type: object +properties: + id: + type: integer + description: Identifier + attribute_display_name: + type: string + description: Attribute display name + attribute_display_type: + type: string + description: Attribute display type (text, number, currency, percent, link, date, list, checkbox) + attribute_description: + type: string + description: Attribute description + attribute_key: + type: string + description: Attribute unique key value + attribute_values: + type: string + description: Attribute values + default_value: + type: string + description: Attribute default value + attribute_model: + type: string + description: Attribute type(conversation_attribute/contact_attribute) + account_id: + type: integer + description: Account Id diff --git a/swagger/index.yml b/swagger/index.yml index 181fed1a8..b2dd91e46 100644 --- a/swagger/index.yml +++ b/swagger/index.yml @@ -66,6 +66,7 @@ x-tagGroups: - Teams - Custom Filters - Reports + - Custom Attributes - name: Client tags: - Contacts API diff --git a/swagger/paths/application/custom_attributes/create.yml b/swagger/paths/application/custom_attributes/create.yml new file mode 100644 index 000000000..fa01fc8e4 --- /dev/null +++ b/swagger/paths/application/custom_attributes/create.yml @@ -0,0 +1,20 @@ +tags: + - Custom Attributes +operationId: add-new-custom-attribute-to-account +summary: Add a new custom attribute +description: Add a new custom attribute to account +security: + - userApiKey: [] +parameters: + - name: data + in: body + required: true + schema: + $ref: '#/definitions/custom_attribute_create_update_payload' +responses: + 200: + description: Success + schema: + $ref: '#/definitions/custom_attribute' + 403: + description: Access denied diff --git a/swagger/paths/application/custom_attributes/delete.yml b/swagger/paths/application/custom_attributes/delete.yml new file mode 100644 index 000000000..cfdb68adc --- /dev/null +++ b/swagger/paths/application/custom_attributes/delete.yml @@ -0,0 +1,20 @@ +tags: + - Custom Attributes +operationId: delete-custom-attribute-from-account +summary: Remove a custom attribute from account +description: Remove a custom attribute from account +security: + - userApiKey: [] +parameters: + - in: path + name: id + type: integer + required: true + description: The ID of the custom attribute to be deleted +responses: + 200: + description: Success + 404: + description: Custom attribute not found + 403: + description: Access denied diff --git a/swagger/paths/application/custom_attributes/index.yml b/swagger/paths/application/custom_attributes/index.yml new file mode 100644 index 000000000..a3a91144b --- /dev/null +++ b/swagger/paths/application/custom_attributes/index.yml @@ -0,0 +1,24 @@ +tags: + - Custom Attributes +operationId: get-account-custom-attribute +summary: List all custom attributes in an account +parameters: + - name: attribute_model + in: query + type: string + enum: ['0', '1'] + description: conversation_attribute(0)/contact_attribute(1) + required: true +description: Get details of custom attributes in an Account +security: + - userApiKey: [] +responses: + 200: + description: Success + schema: + type: array + description: 'Array of all custom attributes' + items: + $ref: '#/definitions/custom_attribute' + 403: + description: Access denied diff --git a/swagger/paths/application/custom_attributes/show.yml b/swagger/paths/application/custom_attributes/show.yml new file mode 100644 index 000000000..4e6f61e49 --- /dev/null +++ b/swagger/paths/application/custom_attributes/show.yml @@ -0,0 +1,14 @@ +tags: + - Custom Attributes +operationId: get-details-of-a-single-custom-attribute +summary: Get a custom attribute details +description: Get the details of a custom attribute in the account +responses: + 200: + description: Success + schema: + $ref: '#/definitions/custom_attribute' + 401: + description: Unauthorized + 404: + description: The given attribute ID does not exist in the account diff --git a/swagger/paths/application/custom_attributes/update.yml b/swagger/paths/application/custom_attributes/update.yml new file mode 100644 index 000000000..4b69f21bd --- /dev/null +++ b/swagger/paths/application/custom_attributes/update.yml @@ -0,0 +1,28 @@ +tags: + - Custom Attributes +operationId: update-custom-attribute-in-account +summary: Update custom attribute in Account +description: Update a custom attribute in account +security: + - userApiKey: [] +parameters: + - in: path + name: id + type: integer + required: true + description: The ID of the custom attribute to be updated. + - name: data + in: body + required: true + schema: + $ref: '#/definitions/custom_attribute_create_update_payload' +responses: + 200: + description: Success + schema: + description: 'The updated custom attribute' + $ref: '#/definitions/custom_attribute' + 404: + description: Agent not found + 403: + description: Access denied diff --git a/swagger/paths/index.yml b/swagger/paths/index.yml index dc00c9b24..87faec643 100644 --- a/swagger/paths/index.yml +++ b/swagger/paths/index.yml @@ -170,6 +170,24 @@ delete: $ref: ./application/canned_responses/delete.yml +# Custom Attributes +/api/v1/accounts/{account_id}/custom_attribute_definitions: + parameters: + - $ref: '#/parameters/account_id' + get: + $ref: ./application/custom_attributes/index.yml + post: + $ref: ./application/custom_attributes/create.yml +/api/v1/accounts/{account_id}/custom_attribute_definitions/{id}: + parameters: + - $ref: '#/parameters/account_id' + get: + $ref: './application/custom_attributes/show.yml' + patch: + $ref: ./application/custom_attributes/update.yml + delete: + $ref: ./application/custom_attributes/delete.yml + # Contacts /api/v1/accounts/{account_id}/contacts: $ref: ./application/contacts/list_create.yml diff --git a/swagger/swagger.json b/swagger/swagger.json index 6e188ad5e..b654a669b 100644 --- a/swagger/swagger.json +++ b/swagger/swagger.json @@ -1494,6 +1494,202 @@ } } }, + "/api/v1/accounts/{account_id}/custom_attribute_definitions": { + "parameters": [ + { + "$ref": "#/parameters/account_id" + } + ], + "get": { + "tags": [ + "Custom Attributes" + ], + "operationId": "get-account-custom-attribute", + "summary": "List all custom attributes in an account", + "parameters": [ + { + "name": "attribute_model", + "in": "query", + "type": "string", + "enum": [ + "0", + "1" + ], + "description": "conversation_attribute(0)/contact_attribute(1)", + "required": true + } + ], + "description": "Get details of custom attributes in an Account", + "security": [ + { + "userApiKey": [ + + ] + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "type": "array", + "description": "Array of all custom attributes", + "items": { + "$ref": "#/definitions/custom_attribute" + } + } + }, + "403": { + "description": "Access denied" + } + } + }, + "post": { + "tags": [ + "Custom Attributes" + ], + "operationId": "add-new-custom-attribute-to-account", + "summary": "Add a new custom attribute", + "description": "Add a new custom attribute to account", + "security": [ + { + "userApiKey": [ + + ] + } + ], + "parameters": [ + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/custom_attribute_create_update_payload" + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/custom_attribute" + } + }, + "403": { + "description": "Access denied" + } + } + } + }, + "/api/v1/accounts/{account_id}/custom_attribute_definitions/{id}": { + "parameters": [ + { + "$ref": "#/parameters/account_id" + } + ], + "get": { + "tags": [ + "Custom Attributes" + ], + "operationId": "get-details-of-a-single-custom-attribute", + "summary": "Get a custom attribute details", + "description": "Get the details of a custom attribute in the account", + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/custom_attribute" + } + }, + "401": { + "description": "Unauthorized" + }, + "404": { + "description": "The given attribute ID does not exist in the account" + } + } + }, + "patch": { + "tags": [ + "Custom Attributes" + ], + "operationId": "update-custom-attribute-in-account", + "summary": "Update custom attribute in Account", + "description": "Update a custom attribute in account", + "security": [ + { + "userApiKey": [ + + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "type": "integer", + "required": true, + "description": "The ID of the custom attribute to be updated." + }, + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/custom_attribute_create_update_payload" + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/custom_attribute" + } + }, + "404": { + "description": "Agent not found" + }, + "403": { + "description": "Access denied" + } + } + }, + "delete": { + "tags": [ + "Custom Attributes" + ], + "operationId": "delete-custom-attribute-from-account", + "summary": "Remove a custom attribute from account", + "description": "Remove a custom attribute from account", + "security": [ + { + "userApiKey": [ + + ] + } + ], + "parameters": [ + { + "in": "path", + "name": "id", + "type": "integer", + "required": true, + "description": "The ID of the custom attribute to be deleted" + } + ], + "responses": { + "200": { + "description": "Success" + }, + "404": { + "description": "Custom attribute not found" + }, + "403": { + "description": "Access denied" + } + } + } + }, "/api/v1/accounts/{account_id}/contacts": { "get": { "tags": [ @@ -4058,6 +4254,47 @@ } } }, + "custom_attribute": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "description": "Identifier" + }, + "attribute_display_name": { + "type": "string", + "description": "Attribute display name" + }, + "attribute_display_type": { + "type": "string", + "description": "Attribute display type (text, number, currency, percent, link, date, list, checkbox)" + }, + "attribute_description": { + "type": "string", + "description": "Attribute description" + }, + "attribute_key": { + "type": "string", + "description": "Attribute unique key value" + }, + "attribute_values": { + "type": "string", + "description": "Attribute values" + }, + "default_value": { + "type": "string", + "description": "Attribute default value" + }, + "attribute_model": { + "type": "string", + "description": "Attribute type(conversation_attribute/contact_attribute)" + }, + "account_id": { + "type": "integer", + "description": "Account Id" + } + } + }, "contact": { "type": "object", "properties": { @@ -4718,6 +4955,38 @@ } } }, + "custom_attribute_create_update_payload": { + "type": "object", + "properties": { + "attribute_display_name": { + "type": "string", + "description": "Attribute display name" + }, + "attribute_display_type": { + "type": "integer", + "description": "Attribute display type (text- 0, number- 1, currency- 2, percent- 3, link- 4, date- 5, list- 6, checkbox- 7)" + }, + "attribute_description": { + "type": "string", + "description": "Attribute description" + }, + "attribute_key": { + "type": "string", + "description": "Attribute unique key value" + }, + "attribute_values": { + "type": "array", + "description": "Attribute values", + "items": { + "type": "string" + } + }, + "attribute_model": { + "type": "integer", + "description": "Attribute type(conversation_attribute- 0, contact_attribute- 1)" + } + } + }, "contact_create": { "type": "object", "required": [ @@ -5449,7 +5718,8 @@ "Profile", "Teams", "Custom Filters", - "Reports" + "Reports", + "Custom Attributes" ] }, {