DEVEXP-469: SMS's javadoc (#194)

* doc (SMS): SMS's javadoc

client/src/main/com/sinch/sdk/domains/sms/SMSService.java

@@ -15,7 +15,7 @@ public interface SMSService {
    * @return V1 service instance for project
    * @see <a
    *     href="https://developers.sinch.com/docs/sms/sdks/java/syntax-reference/">Documentation</a>
-   * @since
+   * @since 1.5
    */
   com.sinch.sdk.domains.sms.api.v1.SMSService v1();
 

client/src/main/com/sinch/sdk/domains/sms/api/v1/SMSService.java

@@ -1,14 +1,51 @@
 package com.sinch.sdk.domains.sms.api.v1;
 
+/**
+ * SMS Service
+ *
+ * @see <a
+ *     href="https://developers.sinch.com/docs/sms/api-reference/">https://developers.sinch.com/docs/sms/api-reference/</a>
+ * @since 1.5
+ */
 public interface SMSService {
 
+  /**
+   * Batches Service instance
+   *
+   * @return service instance for project
+   * @since 1.5
+   */
   BatchesService batches();
 
+  /**
+   * Inbounds Service instance
+   *
+   * @return service instance for project
+   * @since 1.5
+   */
   InboundsService inbounds();
 
+  /**
+   * Delivery Reports Service instance
+   *
+   * @return service instance for project
+   * @since 1.5
+   */
   DeliveryReportsService deliveryReports();
 
+  /**
+   * Groups Service instance
+   *
+   * @return service instance for project
+   * @since 1.5
+   */
   GroupsService groups();
 
+  /**
+   * WebHooksService Service instance
+   *
+   * @return service instance for project
+   * @since 1.5
+   */
   WebHooksService webhooks();
 }

client/src/main/com/sinch/sdk/domains/sms/api/v1/WebHooksService.java

@@ -4,6 +4,40 @@
 import com.sinch.sdk.domains.sms.models.v1.webhooks.SmsEvent;
 import java.util.Map;
 
+/**
+ * SMS WebHooks service
+ *
+ * <p><b>Callbacks</b>
+ *
+ * <p>A callback is an HTTP POST request with a notification made by the Sinch SMS REST API to a URI
+ * of your choosing.
+ *
+ * <p>The REST API expects the receiving server to respond with a response code within the <code>2xx
+ * </code> success range. For <code>5xx</code> the callback will be retried. For <code>429</code>
+ * the callback will be retried and the throughput will be lowered. For other status codes in the
+ * <code>4xx</code> range the callback will not be retried. The first initial retry will happen 5
+ * seconds after the first try. The next attempt is after 10 seconds, then after 20 seconds, after
+ * 40 seconds, after 80 seconds, doubling on every attempt. The last retry will be at 81920 seconds
+ * (or 22 hours 45 minutes) after the initial failed attempt.
+ *
+ * <p>The SMS REST API offers the following callback options which can be configured for your
+ * account upon request to your account manager.
+ *
+ * <ul>
+ *   <li>Callback with mutual authentication over TLS (HTTPS) connection by provisioning the
+ *       callback URL with client keystore and password.
+ *   <li>Callback with basic authentication by provisioning the callback URL with username and
+ *       password.
+ *   <li>Callback with OAuth 2.0 by provisioning the callback URL with username, password and the
+ *       URL to fetch OAuth access token.
+ *   <li>Callback using AWS SNS by provisioning the callback URL with an Access Key ID, Secret Key
+ *       and Region.
+ * </ul>
+ *
+ * @see <a
+ *     href="https://developers.sinch.com/docs/sms/api-reference/sms/tag/Webhooks/">https://developers.sinch.com/docs/sms/api-reference/sms/tag/Webhooks/</a>
+ * @since 1.5
+ */
 public interface WebHooksService {
 
   SmsEvent parseEvent(String jsonPayload) throws ApiMappingException;

client/src/main/com/sinch/sdk/domains/sms/api/v1/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * SMS API interface
+ *
+ * @since 1.5
+ */
+package com.sinch.sdk.domains.sms.api.v1;

client/src/main/com/sinch/sdk/domains/sms/models/v1/batches/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * SMS Batches API related models
+ *
+ * @since 1.5
+ */
+package com.sinch.sdk.domains.sms.models.v1.batches;

client/src/main/com/sinch/sdk/domains/sms/models/v1/batches/request/BatchRequest.java

@@ -1,3 +1,11 @@
 package com.sinch.sdk.domains.sms.models.v1.batches.request;
 
+/**
+ * Base class for all batch request classes
+ *
+ * @see com.sinch.sdk.domains.sms.api.v1.BatchesService#send(BatchRequest)
+ * @see com.sinch.sdk.domains.sms.api.v1.BatchesService#dryRun(BatchRequest)
+ * @see com.sinch.sdk.domains.sms.api.v1.BatchesService#replace(String, BatchRequest)
+ * @since 1.5
+ */
 public interface BatchRequest {}

client/src/main/com/sinch/sdk/domains/sms/models/v1/batches/request/UpdateBatchRequest.java

@@ -1,3 +1,9 @@
 package com.sinch.sdk.domains.sms.models.v1.batches.request;
 
+/**
+ * Base class for all classes supported to <code>update</code> batches
+ *
+ * @see com.sinch.sdk.domains.sms.api.v1.BatchesService#update(String, UpdateBatchRequest)
+ * @since 1.5
+ */
 public interface UpdateBatchRequest {}

client/src/main/com/sinch/sdk/domains/sms/models/v1/batches/request/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Batches API requests related models
+ *
+ * @since 1.5
+ */
+package com.sinch.sdk.domains.sms.models.v1.batches.request;

client/src/main/com/sinch/sdk/domains/sms/models/v1/batches/response/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Batches API responses related models
+ *
+ * @since 1.5
+ */
+package com.sinch.sdk.domains.sms.models.v1.batches.response;

client/src/main/com/sinch/sdk/domains/sms/models/v1/deliveryreports/BatchDeliveryReport.java

@@ -2,6 +2,15 @@
 
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.sinch.sdk.domains.sms.models.v1.deliveryreports.internal.BatchDeliveryReportOneOfImpl;
+import com.sinch.sdk.domains.sms.models.v1.deliveryreports.request.BatchDeliveryReportQueryParameters;
 
+/**
+ * Base class for all classes supporting Batch DeliveryReport
+ *
+ * @see com.sinch.sdk.domains.sms.api.v1.DeliveryReportsService#get(String,
+ *     BatchDeliveryReportQueryParameters)
+ * @see com.sinch.sdk.domains.sms.api.v1.WebHooksService#parseEvent(String)
+ * @since 1.5
+ */
 @JsonDeserialize(using = BatchDeliveryReportOneOfImpl.Deserializer.class)
 public interface BatchDeliveryReport extends DeliveryReport {}

client/src/main/com/sinch/sdk/domains/sms/models/v1/deliveryreports/DeliveryReport.java

@@ -2,4 +2,10 @@
 
 import com.sinch.sdk.domains.sms.models.v1.webhooks.SmsEvent;
 
+/**
+ * Base class for all classes supporting DeliveryReport
+ *
+ * @see com.sinch.sdk.domains.sms.api.v1.WebHooksService#parseEvent(String)
+ * @since 1.5
+ */
 public interface DeliveryReport extends SmsEvent {}

client/src/main/com/sinch/sdk/domains/sms/models/v1/deliveryreports/RecipientDeliveryReport.java

@@ -2,6 +2,16 @@
 
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.sinch.sdk.domains.sms.models.v1.deliveryreports.internal.RecipientDeliveryReportOneOfImpl;
+import com.sinch.sdk.domains.sms.models.v1.deliveryreports.request.ListDeliveryReportsQueryParameters;
 
+/**
+ * Base class for all classes supporting Recipient DeliveryReport
+ *
+ * @see com.sinch.sdk.domains.sms.api.v1.DeliveryReportsService#getForNumber(String, String)
+ * @see
+ *     com.sinch.sdk.domains.sms.api.v1.DeliveryReportsService#list(ListDeliveryReportsQueryParameters)
+ * @see com.sinch.sdk.domains.sms.api.v1.WebHooksService#parseEvent(String)
+ * @since 1.5
+ */
 @JsonDeserialize(using = RecipientDeliveryReportOneOfImpl.Deserializer.class)
 public interface RecipientDeliveryReport extends DeliveryReport {}

client/src/main/com/sinch/sdk/domains/sms/models/v1/deliveryreports/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * SMS Delivery Reports API related models
+ *
+ * @since 1.5
+ */
+package com.sinch.sdk.domains.sms.models.v1.deliveryreports;

client/src/main/com/sinch/sdk/domains/sms/models/v1/deliveryreports/request/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Delivery Reports API requests related models
+ *
+ * @since 1.5
+ */
+package com.sinch.sdk.domains.sms.models.v1.deliveryreports.request;

client/src/main/com/sinch/sdk/domains/sms/models/v1/deliveryreports/response/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Delivery Reports API responses related models
+ *
+ * @since 1.5
+ */
+package com.sinch.sdk.domains.sms.models.v1.deliveryreports.response;

client/src/main/com/sinch/sdk/domains/sms/models/v1/groups/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * SMS Groups API related models
+ *
+ * @since 1.5
+ */
+package com.sinch.sdk.domains.sms.models.v1.groups;

client/src/main/com/sinch/sdk/domains/sms/models/v1/groups/request/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Groups API requests related models
+ *
+ * @since 1.5
+ */
+package com.sinch.sdk.domains.sms.models.v1.groups.request;

client/src/main/com/sinch/sdk/domains/sms/models/v1/groups/response/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Groups API responses related models
+ *
+ * @since 1.5
+ */
+package com.sinch.sdk.domains.sms.models.v1.groups.response;

client/src/main/com/sinch/sdk/domains/sms/models/v1/inbounds/InboundMessage.java

@@ -1,8 +1,17 @@
 package com.sinch.sdk.domains.sms.models.v1.inbounds;
 
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.sinch.sdk.domains.sms.models.v1.inbounds.request.ListInboundMessagesQueryParameters;
 import com.sinch.sdk.domains.sms.models.v1.inbounds.response.internal.InboundInternalImpl;
 import com.sinch.sdk.domains.sms.models.v1.webhooks.SmsEvent;
 
+/**
+ * Base class for all classes supporting InBounds
+ *
+ * @see com.sinch.sdk.domains.sms.api.v1.InboundsService#get(String)
+ * @see com.sinch.sdk.domains.sms.api.v1.InboundsService#list(ListInboundMessagesQueryParameters)
+ * @see com.sinch.sdk.domains.sms.api.v1.WebHooksService#parseEvent(String)
+ * @since 1.5
+ */
 @JsonDeserialize(using = InboundInternalImpl.Deserializer.class)
 public interface InboundMessage extends SmsEvent {}

client/src/main/com/sinch/sdk/domains/sms/models/v1/inbounds/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * SMS Inbounds API related models
+ *
+ * @since 1.5
+ */
+package com.sinch.sdk.domains.sms.models.v1.inbounds;

client/src/main/com/sinch/sdk/domains/sms/models/v1/inbounds/request/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Inbounds API requests related models
+ *
+ * @since 1.5
+ */
+package com.sinch.sdk.domains.sms.models.v1.inbounds.request;

client/src/main/com/sinch/sdk/domains/sms/models/v1/inbounds/response/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Inbounds API responses related models
+ *
+ * @since 1.5
+ */
+package com.sinch.sdk.domains.sms.models.v1.inbounds.response;

client/src/main/com/sinch/sdk/domains/sms/models/v1/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * SMS API related models
+ *
+ * @since 1.5
+ */
+package com.sinch.sdk.domains.sms.models.v1;

client/src/main/com/sinch/sdk/domains/sms/models/v1/webhooks/SmsEvent.java

@@ -3,6 +3,11 @@
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.sinch.sdk.domains.sms.models.v1.webhooks.internal.WebhookEventOneOfImpl;
 
-/** Interface defining a WebHook event */
+/**
+ * Base class for all WebHook event's class
+ *
+ * @see com.sinch.sdk.domains.sms.api.v1.WebHooksService#parseEvent(String)
+ * @since 1.5
+ */
 @JsonDeserialize(using = WebhookEventOneOfImpl.Deserializer.class)
 public interface SmsEvent {}

client/src/main/com/sinch/sdk/domains/sms/models/v1/webhooks/package-info.java

@@ -0,0 +1,57 @@
+/**
+ * SMS API webhooks related models
+ *
+ * <h2>Incoming SMS WebHook</h2>
+ *
+ * <p>An inbound message is a message sent to one of your short codes or long numbers from a mobile
+ * phone. To receive inbound message callbacks, a URL needs to be added to your REST API.
+ *
+ * <p>This URL can be specified in your <a href="https://dashboard.sinch.com/sms/api">Dashboard</a>.
+ *
+ * <p>See <a
+ * href="https://developers.sinch.com/docs/sms/api-reference/sms/tag/Webhooks/#tag/Webhooks/operation/incomingSMS">https://developers.sinch.com/docs/sms/api-reference/sms/tag/Webhooks/#tag/Webhooks/operation/incomingSMS</a>
+ *
+ * <h2>Delivery Report WebHook</h2>
+ *
+ * <p>A delivery report contains the status and status code for each recipient of a batch. To get a
+ * delivery report callback for a message or batch of messages, set the <code>delivery_report
+ * </code> field accordingly when creating a batch.
+ *
+ * <p>The following is provided so you can better understand our webhooks/callbacks. Configuration
+ * of both webhooks and the type of delivery report requested happens when sending a batch.
+ *
+ * <p><b>Callback URL</b>
+ *
+ * <p>The callback URL can either be provided for each batch or provisioned globally for your
+ * account in your <a href="https://dashboard.sinch.com/sms/api/rest">Sinch Customer Dashboard</a>.
+ * Learn how to configure a webhook/callback <a
+ * href="https://community.sinch.com/t5/SMS/How-do-I-assign-a-callback-URL-to-an-SMS-service-plan/ta-p/8414">here</a>
+ *
+ * <p><b>Type</b>
+ *
+ * <p>The <code>type</code> is the type of delivery report webhook. The response will vary depending
+ * on the webhook delivery report you selected when the batch was sent, so choose the appropriate
+ * selection under "One of".
+ *
+ * <ul>
+ *   <li>The <code>delivery_report_sms</code> and <code>delivery_report_mms</code> types are
+ *       documented under <b>Delivery report</b>.
+ *       <p>These are reports containing <a
+ *       href="https://developers.sinch.com/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/SendSMS!path=0/delivery_report&amp;t=request">either
+ *       a full report or summary report</a>, depending on your selection at the time the batch was
+ *       sent.
+ *   <li>The <code>recipient_delivery_report_sms</code> and <code>recipient_delivery_report_mms
+ *       </code> delivery report types are documented under <b>Recipient delivery report</b>.
+ *       <p>These are delivery reports for recipient phone numbers. If you set <code>per_recipient
+ *       </code> for the <code>delivery_report</code> parameter when sending the batch, a recipient
+ *       report gets sent to you for each status change for each recipient in your batch. If you set
+ *       <code>per_recipient_final</code>, a recipient report gets sent to you for the final status
+ *       of each recipient in your batch.
+ * </ul>
+ *
+ * See <a
+ * href="https://developers.sinch.com/docs/sms/api-reference/sms/tag/Webhooks/#tag/Webhooks/operation/deliveryReport">https://developers.sinch.com/docs/sms/api-reference/sms/tag/Webhooks/#tag/Webhooks/operation/deliveryReport</a>
+ *
+ * @since 1.5
+ */
+package com.sinch.sdk.domains.sms.models.v1.webhooks;

client/src/main/com/sinch/sdk/package-info.java

@@ -1,5 +1,5 @@
 /**
- * Sinch Java SDK for Numbers, SMS & Verification
+ * Sinch Java SDK for Conversation, Numbers, SMS, Verification & Voice
  *
  * <p>Provides the client necessary to interface with Sinch APIS
  *

openapi-contracts/src/main/com/sinch/sdk/domains/sms/api/v1/BatchesService.java

@@ -20,6 +20,7 @@
 import com.sinch.sdk.domains.sms.models.v1.batches.response.DryRunResponse;
 import com.sinch.sdk.domains.sms.models.v1.batches.response.ListBatchesResponse;
 
+/** Batches Service */
 public interface BatchesService {
 
   /**

openapi-contracts/src/main/com/sinch/sdk/domains/sms/api/v1/DeliveryReportsService.java

@@ -17,6 +17,7 @@
 import com.sinch.sdk.domains.sms.models.v1.deliveryreports.request.ListDeliveryReportsQueryParameters;
 import com.sinch.sdk.domains.sms.models.v1.deliveryreports.response.ListDeliveryReportsResponse;
 
+/** Delivery reports Service */
 public interface DeliveryReportsService {
 
   /**

openapi-contracts/src/main/com/sinch/sdk/domains/sms/api/v1/GroupsService.java

@@ -18,6 +18,7 @@
 import com.sinch.sdk.domains.sms.models.v1.groups.response.ListGroupsResponse;
 import java.util.List;
 
+/** Groups Service */
 public interface GroupsService {
 
   /**

openapi-contracts/src/main/com/sinch/sdk/domains/sms/api/v1/InboundsService.java

@@ -15,6 +15,7 @@
 import com.sinch.sdk.domains.sms.models.v1.inbounds.request.ListInboundMessagesQueryParameters;
 import com.sinch.sdk.domains.sms.models.v1.inbounds.response.ListInboundsResponse;
 
+/** Inbounds Service */
 public interface InboundsService {
 
   /**