From 776ea6d39afd4a3f4c50c34613109f279d76266a Mon Sep 17 00:00:00 2001 From: Tejaswini Chile Date: Thu, 25 May 2023 18:50:00 +0530 Subject: [PATCH] fix: Help center api doc (#7189) --- swagger/definitions/index.yml | 18 + .../portal/article_create_update_payload.yml | 34 ++ .../portal/category_create_update_payload.yml | 28 + .../portal/portal_create_update_payload.yml | 36 ++ swagger/definitions/resource/article.yml | 33 ++ swagger/definitions/resource/category.yml | 25 + swagger/definitions/resource/portal.yml | 34 ++ swagger/index.yml | 1 + swagger/parameters/portal_id.yml | 5 + swagger/paths/application/article/create.yml | 20 + swagger/paths/application/category/create.yml | 20 + swagger/paths/application/portal/create.yml | 20 + swagger/paths/application/portal/index.yml | 19 + swagger/paths/application/portal/update.yml | 20 + swagger/paths/index.yml | 29 + swagger/swagger.json | 508 +++++++++++++++++- 16 files changed, 849 insertions(+), 1 deletion(-) create mode 100644 swagger/definitions/request/portal/article_create_update_payload.yml create mode 100644 swagger/definitions/request/portal/category_create_update_payload.yml create mode 100644 swagger/definitions/request/portal/portal_create_update_payload.yml create mode 100644 swagger/definitions/resource/article.yml create mode 100644 swagger/definitions/resource/category.yml create mode 100644 swagger/definitions/resource/portal.yml create mode 100644 swagger/parameters/portal_id.yml create mode 100644 swagger/paths/application/article/create.yml create mode 100644 swagger/paths/application/category/create.yml create mode 100644 swagger/paths/application/portal/create.yml create mode 100644 swagger/paths/application/portal/index.yml create mode 100644 swagger/paths/application/portal/update.yml diff --git a/swagger/definitions/index.yml b/swagger/definitions/index.yml index 3f70db3f9..ccc288180 100644 --- a/swagger/definitions/index.yml +++ b/swagger/definitions/index.yml @@ -18,6 +18,16 @@ custom_attribute: $ref: ./resource/custom_attribute.yml automation_rule: $ref: ./resource/automation_rule.yml +portal: + $ref: ./resource/portal.yml +category: + $ref: ./resource/category.yml +article: + $ref: ./resource/article.yml +category: + $ref: ./resource/category.yml +article: + $ref: ./resource/article.yml contact: $ref: ./resource/contact.yml conversation: @@ -110,6 +120,14 @@ integrations_hook_update_payload: automation_rule_create_update_payload: $ref: ./request/automation_rule/create_update_payload.yml +# Help Center +portal_create_update_payload: + $ref: ./request/portal/portal_create_update_payload.yml +category_create_update_payload: + $ref: ./request/portal/category_create_update_payload.yml +article_create_update_payload: + $ref: ./request/portal/article_create_update_payload.yml + ## public requests public_contact_create_update_payload: diff --git a/swagger/definitions/request/portal/article_create_update_payload.yml b/swagger/definitions/request/portal/article_create_update_payload.yml new file mode 100644 index 000000000..cddac1d1d --- /dev/null +++ b/swagger/definitions/request/portal/article_create_update_payload.yml @@ -0,0 +1,34 @@ +type: object +properties: + content: + type: string + description: The text content. + meta: + type: object + description: Use for search + example: { tags: ['article_name'], title: 'article title', description: 'article description' } + position: + type: integer + description: article position in category + status: + type: integer + example: ['draft', 'published', 'archived'] + title: + type: string + slug: + type: string + views: + type: integer + portal_id: + type: integer + account_id: + type: integer + author_id: + type: integer + category_id: + type: integer + folder_id: + type: integer + associated_article_id: + type: integer + description: To associate similar articles to each other, e.g to provide the link for the reference. diff --git a/swagger/definitions/request/portal/category_create_update_payload.yml b/swagger/definitions/request/portal/category_create_update_payload.yml new file mode 100644 index 000000000..0d1ce5c8f --- /dev/null +++ b/swagger/definitions/request/portal/category_create_update_payload.yml @@ -0,0 +1,28 @@ +type: object +properties: + description: + type: string + description: Category description + locale: + type: string + description: Category locale + example: en/es + name: + type: string + description: Category name + slug: + type: string + description: Category slug + position: + type: integer + description: Category position in the portal list to sort + portal_id: + type: integer + account_id: + type: integer + associated_category_id: + type: integer + description: To associate similar categories to each other, e.g same category of product documentation in different languages + parent_category_id: + type: integer + description: To define parent category, e.g product documentation has multiple level features in sales category or in engineering category. diff --git a/swagger/definitions/request/portal/portal_create_update_payload.yml b/swagger/definitions/request/portal/portal_create_update_payload.yml new file mode 100644 index 000000000..d1e82aaf4 --- /dev/null +++ b/swagger/definitions/request/portal/portal_create_update_payload.yml @@ -0,0 +1,36 @@ +type: object +properties: + archived: + type: boolean + description: Status to check if portal is live + color: + type: string + description: Header color for help-center + example: add color HEX string, "#fffff" + config: + type: object + description: Configuration about supporting locales + example: { allowed_locales: ['en', 'es'], default_locale: 'en' } + custom_domain: + type: string + description: Custom domain to display help center. + example: https://chatwoot.help/. + header_text: + type: string + description: Help center header + example: Handbook + homepage_link: + type: string + description: link to main dashboard + example: https://www.chatwoot.com/ + name: + type: string + description: Name for the portal + slug: + type: string + description: Slug for the portal to display in link + page_title: + type: string + description: Page title for the portal + account_id: + type: integer diff --git a/swagger/definitions/resource/article.yml b/swagger/definitions/resource/article.yml new file mode 100644 index 000000000..1624c45d2 --- /dev/null +++ b/swagger/definitions/resource/article.yml @@ -0,0 +1,33 @@ +type: object +properties: + id: + type: integer + content: + type: string + description: The text content. + meta: + type: object + position: + type: integer + status: + type: integer + enum: ['draft', 'published', 'archived'] + title: + type: string + slug: + type: string + views: + type: integer + portal_id: + type: integer + account_id: + type: integer + author_id: + type: integer + category_id: + type: integer + folder_id: + type: integer + associated_article_id: + type: integer + description: To associate similar articles to each other, e.g to provide the link for the reference. diff --git a/swagger/definitions/resource/category.yml b/swagger/definitions/resource/category.yml new file mode 100644 index 000000000..16c97b8f3 --- /dev/null +++ b/swagger/definitions/resource/category.yml @@ -0,0 +1,25 @@ +type: object +properties: + id: + type: integer + description: + type: string + description: The text content. + locale: + type: string + name: + type: string + slug: + type: string + position: + type: integer + portal_id: + type: integer + account_id: + type: integer + associated_category_id: + type: integer + description: To associate similar categories to each other, e.g same category of product documentation in different languages + parent_category_id: + type: integer + description: To define parent category, e.g product documentation has multiple level features in sales category or in engineering category. diff --git a/swagger/definitions/resource/portal.yml b/swagger/definitions/resource/portal.yml new file mode 100644 index 000000000..a1bef33bc --- /dev/null +++ b/swagger/definitions/resource/portal.yml @@ -0,0 +1,34 @@ +type: object +properties: + id: + type: integer + archived: + type: boolean + color: + type: string + config: + type: object + description: Save information about locales, allowed_locales and default portal/help-center locale + custom_domain: + type: string + header_text: + type: string + description: The text content. + homepage_link: + type: string + name: + type: string + slug: + type: string + page_title: + type: string + account_id: + type: integer + categories: + type: array + items: + $ref: '#/definitions/category' + articles: + type: array + items: + $ref: '#/definitions/article' diff --git a/swagger/index.yml b/swagger/index.yml index 3dc245ddf..bddaf934c 100644 --- a/swagger/index.yml +++ b/swagger/index.yml @@ -69,6 +69,7 @@ x-tagGroups: - Teams - Webhooks - Automation Rule + - Help Center - name: Client tags: - Contacts API diff --git a/swagger/parameters/portal_id.yml b/swagger/parameters/portal_id.yml new file mode 100644 index 000000000..b45f69629 --- /dev/null +++ b/swagger/parameters/portal_id.yml @@ -0,0 +1,5 @@ +in: path +name: portal_id +type: integer +required: true +description: The numeric ID of the portal diff --git a/swagger/paths/application/article/create.yml b/swagger/paths/application/article/create.yml new file mode 100644 index 000000000..0733fb860 --- /dev/null +++ b/swagger/paths/application/article/create.yml @@ -0,0 +1,20 @@ +tags: + - Help Center +operationId: add-new-article-to-account +summary: Add a new article +description: Add a new article to portal +security: + - userApiKey: [] +parameters: + - name: data + in: body + required: true + schema: + $ref: '#/definitions/article_create_update_payload' +responses: + '200': + description: Success + schema: + $ref: '#/definitions/article' + '403': + description: Access denied diff --git a/swagger/paths/application/category/create.yml b/swagger/paths/application/category/create.yml new file mode 100644 index 000000000..7b569a40b --- /dev/null +++ b/swagger/paths/application/category/create.yml @@ -0,0 +1,20 @@ +tags: + - Help Center +operationId: add-new-category-to-account +summary: Add a new category +description: Add a new category to portal +security: + - userApiKey: [] +parameters: + - name: data + in: body + required: true + schema: + $ref: '#/definitions/category_create_update_payload' +responses: + '200': + description: Success + schema: + $ref: '#/definitions/category' + '403': + description: Access denied diff --git a/swagger/paths/application/portal/create.yml b/swagger/paths/application/portal/create.yml new file mode 100644 index 000000000..187c20008 --- /dev/null +++ b/swagger/paths/application/portal/create.yml @@ -0,0 +1,20 @@ +tags: + - Help Center +operationId: add-new-portal-to-account +summary: Add a new portal +description: Add a new portal to account +security: + - userApiKey: [] +parameters: + - name: data + in: body + required: true + schema: + $ref: '#/definitions/portal_create_update_payload' +responses: + '200': + description: Success + schema: + $ref: '#/definitions/portal' + '403': + description: Access denied diff --git a/swagger/paths/application/portal/index.yml b/swagger/paths/application/portal/index.yml new file mode 100644 index 000000000..ea56563a4 --- /dev/null +++ b/swagger/paths/application/portal/index.yml @@ -0,0 +1,19 @@ +tags: + - Help Center +operationId: get-portal +summary: List all portals in an account +parameters: + - $ref: '#/parameters/account_id' +description: Get details of portals in an Account +security: + - userApiKey: [] +responses: + '200': + description: Success + schema: + type: array + description: Array of all portals + items: + $ref: '#/definitions/portal' + '403': + description: Access denied diff --git a/swagger/paths/application/portal/update.yml b/swagger/paths/application/portal/update.yml new file mode 100644 index 000000000..8c6a74e85 --- /dev/null +++ b/swagger/paths/application/portal/update.yml @@ -0,0 +1,20 @@ +tags: + - Help Center +operationId: update-new-portal-to-account +summary: update a new portal +description: update a new portal to account +security: + - userApiKey: [] +parameters: + - name: data + in: body + required: true + schema: + $ref: '#/definitions/portal_create_update_payload' +responses: + '200': + description: Success + schema: + $ref: '#/definitions/portal' + '403': + description: Access denied diff --git a/swagger/paths/index.yml b/swagger/paths/index.yml index c3e0f9d51..3f208c2c9 100644 --- a/swagger/paths/index.yml +++ b/swagger/paths/index.yml @@ -245,6 +245,35 @@ $ref: ./application/automation_rule/delete.yml +# Help Center +/api/v1/accounts/{account_id}/portals: + parameters: + - $ref: '#/parameters/account_id' + post: + $ref: ./application/portal/create.yml + get: + $ref: ./application/portal/index.yml + patch: + $ref: ./application/portal/update.yml + + +# Help Center category +/api/v1/accounts/{account_id}/portals/{portal_id}/categories: + parameters: + - $ref: '#/parameters/account_id' + - $ref: '#/parameters/portal_id' + post: + $ref: ./application/category/create.yml + +# Help Center article +/api/v1/accounts/{account_id}/portals/{portal_id}/articles: + parameters: + - $ref: '#/parameters/account_id' + - $ref: '#/parameters/portal_id' + post: + $ref: ./application/article/create.yml + + # Conversations /api/v1/accounts/{account_id}/conversations/meta: $ref: ./application/conversation/meta.yml diff --git a/swagger/swagger.json b/swagger/swagger.json index 5ae02e056..c6583cb1e 100644 --- a/swagger/swagger.json +++ b/swagger/swagger.json @@ -2396,6 +2396,212 @@ } } }, + "/api/v1/accounts/{account_id}/portals": { + "parameters": [ + { + "$ref": "#/parameters/account_id" + } + ], + "post": { + "tags": [ + "Help Center" + ], + "operationId": "add-new-portal-to-account", + "summary": "Add a new portal", + "description": "Add a new portal to account", + "security": [ + { + "userApiKey": [ + + ] + } + ], + "parameters": [ + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/portal_create_update_payload" + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/portal" + } + }, + "403": { + "description": "Access denied" + } + } + }, + "get": { + "tags": [ + "Help Center" + ], + "operationId": "get-portal", + "summary": "List all portals in an account", + "parameters": [ + { + "$ref": "#/parameters/account_id" + } + ], + "description": "Get details of portals in an Account", + "security": [ + { + "userApiKey": [ + + ] + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "type": "array", + "description": "Array of all portals", + "items": { + "$ref": "#/definitions/portal" + } + } + }, + "403": { + "description": "Access denied" + } + } + }, + "patch": { + "tags": [ + "Help Center" + ], + "operationId": "update-new-portal-to-account", + "summary": "update a new portal", + "description": "update a new portal to account", + "security": [ + { + "userApiKey": [ + + ] + } + ], + "parameters": [ + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/portal_create_update_payload" + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/portal" + } + }, + "403": { + "description": "Access denied" + } + } + } + }, + "/api/v1/accounts/{account_id}/portals/{portal_id}/categories": { + "parameters": [ + { + "$ref": "#/parameters/account_id" + }, + { + "$ref": "#/parameters/portal_id" + } + ], + "post": { + "tags": [ + "Help Center" + ], + "operationId": "add-new-category-to-account", + "summary": "Add a new category", + "description": "Add a new category to portal", + "security": [ + { + "userApiKey": [ + + ] + } + ], + "parameters": [ + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/category_create_update_payload" + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/category" + } + }, + "403": { + "description": "Access denied" + } + } + } + }, + "/api/v1/accounts/{account_id}/portals/{portal_id}/articles": { + "parameters": [ + { + "$ref": "#/parameters/account_id" + }, + { + "$ref": "#/parameters/portal_id" + } + ], + "post": { + "tags": [ + "Help Center" + ], + "operationId": "add-new-article-to-account", + "summary": "Add a new article", + "description": "Add a new article to portal", + "security": [ + { + "userApiKey": [ + + ] + } + ], + "parameters": [ + { + "name": "data", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/article_create_update_payload" + } + } + ], + "responses": { + "200": { + "description": "Success", + "schema": { + "$ref": "#/definitions/article" + } + }, + "403": { + "description": "Access denied" + } + } + } + }, "/api/v1/accounts/{account_id}/conversations/meta": { "parameters": [ { @@ -4921,6 +5127,150 @@ } } }, + "portal": { + "type": "object", + "properties": { + "id": { + "type": "integer" + }, + "archived": { + "type": "boolean" + }, + "color": { + "type": "string" + }, + "config": { + "type": "object", + "description": "Save information about locales, allowed_locales and default portal/help-center locale" + }, + "custom_domain": { + "type": "string" + }, + "header_text": { + "type": "string", + "description": "The text content." + }, + "homepage_link": { + "type": "string" + }, + "name": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "page_title": { + "type": "string" + }, + "account_id": { + "type": "integer" + }, + "categories": { + "type": "array", + "items": { + "$ref": "#/definitions/category" + } + }, + "articles": { + "type": "array", + "items": { + "$ref": "#/definitions/article" + } + } + } + }, + "category": { + "type": "object", + "properties": { + "id": { + "type": "integer" + }, + "description": { + "type": "string", + "description": "The text content." + }, + "locale": { + "type": "string" + }, + "name": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "position": { + "type": "integer" + }, + "portal_id": { + "type": "integer" + }, + "account_id": { + "type": "integer" + }, + "associated_category_id": { + "type": "integer", + "description": "To associate similar categories to each other, e.g same category of product documentation in different languages" + }, + "parent_category_id": { + "type": "integer", + "description": "To define parent category, e.g product documentation has multiple level features in sales category or in engineering category." + } + } + }, + "article": { + "type": "object", + "properties": { + "id": { + "type": "integer" + }, + "content": { + "type": "string", + "description": "The text content." + }, + "meta": { + "type": "object" + }, + "position": { + "type": "integer" + }, + "status": { + "type": "integer", + "enum": [ + "draft", + "published", + "archived" + ] + }, + "title": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "views": { + "type": "integer" + }, + "portal_id": { + "type": "integer" + }, + "account_id": { + "type": "integer" + }, + "author_id": { + "type": "integer" + }, + "category_id": { + "type": "integer" + }, + "folder_id": { + "type": "integer" + }, + "associated_article_id": { + "type": "integer", + "description": "To associate similar articles to each other, e.g to provide the link for the reference." + } + } + }, "contact": { "type": "object", "properties": { @@ -6002,6 +6352,161 @@ } } }, + "portal_create_update_payload": { + "type": "object", + "properties": { + "archived": { + "type": "boolean", + "description": "Status to check if portal is live" + }, + "color": { + "type": "string", + "description": "Header color for help-center", + "example": "add color HEX string, \"#fffff\"" + }, + "config": { + "type": "object", + "description": "Configuration about supporting locales", + "example": { + "allowed_locales": [ + "en", + "es" + ], + "default_locale": "en" + } + }, + "custom_domain": { + "type": "string", + "description": "Custom domain to display help center.", + "example": "https://chatwoot.help/." + }, + "header_text": { + "type": "string", + "description": "Help center header", + "example": "Handbook" + }, + "homepage_link": { + "type": "string", + "description": "link to main dashboard", + "example": "https://www.chatwoot.com/" + }, + "name": { + "type": "string", + "description": "Name for the portal" + }, + "slug": { + "type": "string", + "description": "Slug for the portal to display in link" + }, + "page_title": { + "type": "string", + "description": "Page title for the portal" + }, + "account_id": { + "type": "integer" + } + } + }, + "category_create_update_payload": { + "type": "object", + "properties": { + "description": { + "type": "string", + "description": "Category description" + }, + "locale": { + "type": "string", + "description": "Category locale", + "example": "en/es" + }, + "name": { + "type": "string", + "description": "Category name" + }, + "slug": { + "type": "string", + "description": "Category slug" + }, + "position": { + "type": "integer", + "description": "Category position in the portal list to sort" + }, + "portal_id": { + "type": "integer" + }, + "account_id": { + "type": "integer" + }, + "associated_category_id": { + "type": "integer", + "description": "To associate similar categories to each other, e.g same category of product documentation in different languages" + }, + "parent_category_id": { + "type": "integer", + "description": "To define parent category, e.g product documentation has multiple level features in sales category or in engineering category." + } + } + }, + "article_create_update_payload": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "The text content." + }, + "meta": { + "type": "object", + "description": "Use for search", + "example": { + "tags": [ + "article_name" + ], + "title": "article title", + "description": "article description" + } + }, + "position": { + "type": "integer", + "description": "article position in category" + }, + "status": { + "type": "integer", + "example": [ + "draft", + "published", + "archived" + ] + }, + "title": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "views": { + "type": "integer" + }, + "portal_id": { + "type": "integer" + }, + "account_id": { + "type": "integer" + }, + "author_id": { + "type": "integer" + }, + "category_id": { + "type": "integer" + }, + "folder_id": { + "type": "integer" + }, + "associated_article_id": { + "type": "integer", + "description": "To associate similar articles to each other, e.g to provide the link for the reference." + } + } + }, "public_contact_create_update_payload": { "type": "object", "properties": { @@ -6567,7 +7072,8 @@ "Reports", "Teams", "Webhooks", - "Automation Rule" + "Automation Rule", + "Help Center" ] }, {