From 9e888b90717b50d964f1db3fc72db9fe21a46e70 Mon Sep 17 00:00:00 2001 From: Nipuna Ranasinghe Date: Wed, 27 Mar 2024 09:12:41 +0530 Subject: [PATCH 1/2] Fix doc issues --- README.md | 6 +++--- ballerina/Module.md | 6 +++--- ballerina/Package.md | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index ec00623..51ebcb7 100644 --- a/README.md +++ b/README.md @@ -26,15 +26,15 @@ To use the Zendesk Connector in Ballerina, you must have a Zendesk account and a ![Zendesk Admin Center](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-zendesk/master/docs/setup/resources/1-admin-center.png) -### Step 3: Manage API tokens +### Step 3: Create a new connection 1. In the Admin Center, click on **Apps and integrations**. 2. Click on **Connections** under the **Connections** section. 3. Click on **Create connection** to create a new connection. - ![Zendesk Connection Settings](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-zendesk/master/docs/setup/resources/2-connection-settings.png) + ![Zendesk Connection Settings](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-zendesk/master/docs/setup/resources/2-create-connection.png) -### Step 4: Configure & generate the token +### Step 4: Configure connection settings When creating a new connection, you will be prompted to provide the following details: diff --git a/ballerina/Module.md b/ballerina/Module.md index 96395eb..3d0e04f 100644 --- a/ballerina/Module.md +++ b/ballerina/Module.md @@ -20,15 +20,15 @@ To use the Zendesk Connector in Ballerina, you must have a Zendesk account and a ![Zendesk Admin Center](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-zendesk/master/docs/setup/resources/1-admin-center.png) -### Step 3: Manage API tokens +### Step 3: Create a new connection 1. In the Admin Center, click on **Apps and integrations**. 2. Click on **Connections** under the **Connections** section. 3. Click on **Create connection** to create a new connection. - ![Zendesk Connection Settings](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-zendesk/master/docs/setup/resources/2-connection-settings.png) + ![Zendesk Connection Settings](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-zendesk/master/docs/setup/resources/2-create-connection.png) -### Step 4: Configure & generate the token +### Step 4: Configure connection settings When creating a new connection, you will be prompted to provide the following details: diff --git a/ballerina/Package.md b/ballerina/Package.md index 96395eb..3d0e04f 100644 --- a/ballerina/Package.md +++ b/ballerina/Package.md @@ -20,15 +20,15 @@ To use the Zendesk Connector in Ballerina, you must have a Zendesk account and a ![Zendesk Admin Center](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-zendesk/master/docs/setup/resources/1-admin-center.png) -### Step 3: Manage API tokens +### Step 3: Create a new connection 1. In the Admin Center, click on **Apps and integrations**. 2. Click on **Connections** under the **Connections** section. 3. Click on **Create connection** to create a new connection. - ![Zendesk Connection Settings](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-zendesk/master/docs/setup/resources/2-connection-settings.png) + ![Zendesk Connection Settings](https://raw.githubusercontent.com/ballerina-platform/module-ballerinax-zendesk/master/docs/setup/resources/2-create-connection.png) -### Step 4: Configure & generate the token +### Step 4: Configure connection settings When creating a new connection, you will be prompted to provide the following details: From 2932a4b1755e579d148aa923c6719e42c491da5b Mon Sep 17 00:00:00 2001 From: Nipuna Ranasinghe Date: Wed, 27 Mar 2024 09:29:30 +0530 Subject: [PATCH 2/2] Make service url mandatory when initializing the client --- README.md | 2 +- ballerina/Module.md | 2 +- ballerina/Package.md | 2 +- ballerina/client.bal | 2 +- docs/spec/openapi.yaml | 7 ------- docs/spec/sanitations.md | 13 +++++++------ 6 files changed, 11 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 51ebcb7..5039dfe 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ zendesk:ConnectionConfig zendeskConfig = { } }; -zendesk:Client zendesk = check new (zendeskConfig); +zendesk:Client zendesk = check new (zendeskConfig, "https://.zendesk.com"); ``` ### Step 3: Invoke the connector operation diff --git a/ballerina/Module.md b/ballerina/Module.md index 3d0e04f..4cfe608 100644 --- a/ballerina/Module.md +++ b/ballerina/Module.md @@ -65,7 +65,7 @@ zendesk:ConnectionConfig zendeskConfig = { } }; -zendesk:Client zendesk = check new (zendeskConfig); +zendesk:Client zendesk = check new (zendeskConfig, "https://.zendesk.com"); ``` ### Step 3: Invoke the connector operation diff --git a/ballerina/Package.md b/ballerina/Package.md index 3d0e04f..4cfe608 100644 --- a/ballerina/Package.md +++ b/ballerina/Package.md @@ -65,7 +65,7 @@ zendesk:ConnectionConfig zendeskConfig = { } }; -zendesk:Client zendesk = check new (zendeskConfig); +zendesk:Client zendesk = check new (zendeskConfig, "https://.zendesk.com"); ``` ### Step 3: Invoke the connector operation diff --git a/ballerina/client.bal b/ballerina/client.bal index 95b402b..6f95b13 100644 --- a/ballerina/client.bal +++ b/ballerina/client.bal @@ -27,7 +27,7 @@ public isolated client class Client { # + config - The configurations to be used when initializing the `connector` # + serviceUrl - URL of the target service # + return - An error if connector initialization failed - public isolated function init(ConnectionConfig config, string serviceUrl = "https://example.zendesk.com") returns error? { + public isolated function init(ConnectionConfig config, string serviceUrl) returns error? { http:ClientConfiguration httpClientConfig = {auth: config.auth, httpVersion: config.httpVersion, timeout: config.timeout, forwarded: config.forwarded, poolConfig: config.poolConfig, compression: config.compression, circuitBreaker: config.circuitBreaker, retryConfig: config.retryConfig, validation: config.validation}; do { if config.http1Settings is ClientHttp1Settings { diff --git a/docs/spec/openapi.yaml b/docs/spec/openapi.yaml index 85c3b66..720d2a4 100644 --- a/docs/spec/openapi.yaml +++ b/docs/spec/openapi.yaml @@ -72,13 +72,6 @@ tags: - name: Custom Object Records - name: Essentials Card - name: Omnichannel Routing Queues -servers: - - url: https://{subdomain}.{domain}.com - variables: - domain: - default: zendesk - subdomain: - default: example paths: /api/lotus/assignables/autocomplete.json: get: diff --git a/docs/spec/sanitations.md b/docs/spec/sanitations.md index faa3a9f..3538ca1 100644 --- a/docs/spec/sanitations.md +++ b/docs/spec/sanitations.md @@ -16,21 +16,22 @@ These changes are done in order to improve the overall usability, and as workaro 2. Use `--nullable` option when generating the client using the Ballerina OpenAPI tool. * The ZenDesk API reference does not properly include the "nullable" property for some the request and response schemas. - * Therefore, the `--nullable` option is used as a precaution to avoid potential data-binding issues in the runtime, - which will generate all the request/response type fields with the support to handle null values. + * Therefore, the `--nullable` option is used as a precaution to avoid potential data-binding issues in the runtime, which will generate all the request/response type fields with the support to handle null values. * This workaround can be removed once https://github.com/ballerina-platform/ballerina-library/issues/4870 is addressed. 3. Change the types `Organization_field_id` and `User_field_id` from `int|string?` to `int|string`. * This is done as a post-workaround after using the `--nullable` option to generate the client, as nilable types are not supported for path parameters in Ballerina 4. Add `Accept` header (as `application/json`) to all the operations. - * The ZenDesk OpenAPI reference does not include the `Accept` header in the operations, but the server returns an - unsupported media type error if the `Accept` header is not included in the requests. + * The ZenDesk OpenAPI reference does not include the `Accept` header in the operations, but the server returns an unsupported media type error if the `Accept` header is not included in the requests. + +5. Remove `servers` from the OpenAPI specification. + * Zendesk users are required to use their subdomain in the URL path to access the API. + * Therefore, the `servers` field is removed from the OpenAPI specification to make the server a required field when initializing the client. ## OpenAPI cli command -The following command was used to generate the Ballerina client from the OpenAPI specification. The command should be -executed from the repository root directory. +The following command was used to generate the Ballerina client from the OpenAPI specification. The command should be executed from the repository root directory. ```bash bal openapi -i docs/spec/openapi.yaml --mode client --license docs/license.txt -o ballerina/ --nullable